Paperless-ngx¶
Document management.
| Runtime | Container (Docker Swarm), 5 containers: webserver, postgres, broker (redis), gotenberg, tika |
| Tier | Apps (Important) |
| Node | swarm-core |
| Image | ghcr.io/paperless-ngx/paperless-ngx:2.20.15; postgres:16-alpine; redis:7-alpine; gotenberg/gotenberg:8.34.0; apache/tika:3.3.1.0 |
| URL | https://paperless.lab.riversfamily.uk |
| Auth | Native OIDC (via django-allauth) |
| Source | ansible/stacks/apps/paperless-ngx/ |
Five containers, tied with NetBox for the most sidecars in the stack.
gotenberg and tika handle office-document conversion and text
extraction for the OCR pipeline; gotenberg's Chromium is hardened
(--chromium-disable-javascript=true,
--chromium-allow-list=file:///tmp/.*).
Configuration¶
PAPERLESS_APPS=allauth.socialaccount.providers.openid_connect with the
OIDC client config (client_id, secret, server_url) embedded in the
PAPERLESS_SOCIALACCOUNT_PROVIDERS JSON env var. Forwarded-proto trust is
set explicitly (PAPERLESS_USE_X_FORWARD_HOST, _PORT,
PAPERLESS_PROXY_SSL_HEADER).
Volumes¶
| Volume | Path | Backing | Contents |
|---|---|---|---|
data |
/usr/src/paperless/data |
Local | Index and application state |
media |
/usr/src/paperless/media |
Local | Ingested documents |
database |
/var/lib/postgresql/data |
Local | Postgres data — never NFS |
redis (broker) |
/data |
Local | Task queue |
gotenberg and tika have no persistent volumes.
Networking¶
webserver joins both the shared traefik network (for its Traefik route)
and this stack's private internal network. postgres, broker,
gotenberg and tika join internal only — they are unreachable from
every other stack.
Secrets¶
| Vault variable | Delivered as | Purpose |
|---|---|---|
vault_paperless_db_password |
Swarm secret (PAPERLESS_DBPASS_FILE) |
Postgres password |
vault_paperless_secret_key |
Swarm secret (PAPERLESS_SECRET_KEY_FILE) |
Django secret key |
vault_paperless_admin_password |
Swarm secret (PAPERLESS_ADMIN_PASSWORD_FILE) |
Initial admin password |
vault_paperless_oidc_client_secret |
Plain env var, embedded in the PAPERLESS_SOCIALACCOUNT_PROVIDERS JSON |
OIDC client secret |