Your invoices, filed automatically.

Automatically syncs sent invoices from Papierkram to Paperless-ngx. Runs as a single self-hosted container behind a reverse proxy — no separate workers, no message queues.

Table of Contents

• What it does
• Architecture
• Deployment
• Unraid
• Reverse proxy
• Environment variables
• Settings (Web UI)
• Local development
• Tests
• Backup
• Troubleshooting
• Contributing
• Maintainer
• License

What it does

• Polls the Papierkram API every N minutes for sent invoices (state: unpaid | paid | overdue | open)
• Downloads each invoice as PDF
• Uploads it to Paperless-ngx with configurable tags, document type, and correspondent
• Prevents duplicate uploads via a local SQLite dedup table
• Provides a password-protected web dashboard for status, manual sync, dry-run, and logs

Architecture

Internet → Reverse Proxy → PaperSync Container
                                    ↕                    ↕
                          Papierkram API      Paperless-ngx API

Deployment

1. Create the shared Docker network

docker network create internal

2. Generate a secret key

python3 -c "from cryptography.fernet import Fernet; print(Fernet.generate_key().decode())"

3. Create .env

cp .env.example .env

Edit .env and set at minimum:

SECRET_KEY=<generated-key>
APP_USERNAME=admin
APP_PASSWORD=<your-password>

4. Create docker-compose.yml

services:
  papersync:
    image: ghcr.io/furch-services/papersync:latest
    restart: unless-stopped
    env_file: .env
    ports:
      - "8000:8000"
    volumes:
      - ./data:/app/data
      - ./logs:/app/logs
    networks:
      - internal

networks:
  internal:
    external: true

5. Start

docker compose up -d

6. Configure

Open the web UI, log in, and enter your Papierkram and Paperless-ngx credentials under Einstellungen.

Unraid

PaperSync is available in the Unraid Community Applications store. Search for PaperSync and install directly from the CA interface.

Installation via Community Applications

1. In the Unraid web UI, open Apps (Community Applications).
2. Search for PaperSync.
3. Click Install, fill in SECRET_KEY and APP_PASSWORD, and click Apply.

Manual template installation (alternative)

If you prefer to install without CA, add the template URL manually:

1. In the Unraid web UI, go to Docker → Add Container → click Template repositories and add:

   https://raw.githubusercontent.com/furch-services/papersync/main/unraid/papersync.xml
   

2. Click Save — PaperSync now appears in the template list.
3. Select it, fill in SECRET_KEY and APP_PASSWORD, and click Apply.

The data and log directories are automatically created under /mnt/user/appdata/papersync/.

Reverse proxy on Unraid

If you use Nginx Proxy Manager or Swag on Unraid, point a proxy host at http://papersync:8000. Set APP_ENV=production (the default) to keep the secure cookie flag active when running behind HTTPS.

Reverse proxy

Running PaperSync behind a reverse proxy (Caddy, nginx, Traefik, etc.) is recommended for SSL termination, custom domains, and access control. The app listens on port 8000 and respects the X-Forwarded-* headers passed by the proxy.

Environment variables

Settings (Web UI)

All sync settings are stored in the database and configurable via /settings:

Local development

python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt

export SECRET_KEY=$(python3 -c "from cryptography.fernet import Fernet; print(Fernet.generate_key().decode())")
export DATABASE_URL=sqlite:///./data/papersync.db
export APP_PASSWORD=dev
mkdir -p data logs

alembic upgrade head
uvicorn app.main:app --reload

Tests

pytest tests/
# With coverage:
pytest tests/ --cov=app --cov-report=term-missing

Backup

All persistent data lives in ./data/:

# Backup
cp data/papersync.db data/papersync.db.bak

# Restore (container must be stopped)
docker compose stop
cp data/papersync.db.bak data/papersync.db
docker compose up -d

Troubleshooting

No invoices synced: Check the web UI logs. Common cause: Papierkram API key is wrong, or the invoice state doesn't match (unpaid, paid, overdue).

Container won't start / permission error on logs: The bind-mounted ./logs directory may be owned by root. The entrypoint script fixes this automatically on startup.

Auth errors after restart: Session tokens are in-memory — users need to log in again after a container restart.

Too Many Requests from Papierkram: Increase the polling interval in Settings.

Contributing

Contributions are welcome. Please read the project documents before opening a PR:

• CONTRIBUTING.md — dev setup, architecture constraints, PR process
• CODE_OF_CONDUCT.md — community standards
• SECURITY.md — how to report vulnerabilities

Maintainer

PaperSync is developed and maintained by Furch Services — IT-Dienstleister aus Norderstedt.

License

AGPL-3.0