Docs and wikis, checked 2026-09-07
Paperless-ngx: Docker configuration reference
Self-hosted document management system that scans, OCRs, tags and indexes paper and digital documents.
At a glance
- Image:
ghcr.io/paperless-ngx/paperless-ngx - Tags:
latest,3.1.3,3.1,3.0.5 - Licence: GPL-3.0
- Source: https://github.com/paperless-ngx/paperless-ngx
- Docs: https://github.com/paperless-ngx/paperless-ngx/blob/main/docs/index.md
Ports
| Port | What listens | Source |
|---|---|---|
8000 (webserver) | HTTP listener for the web UI and API. Route the reverse proxy here. | source for port 8000 |
Environment variables
| Variable | Required | What it does | Example | Source |
|---|---|---|---|---|
PAPERLESS_URL | No | Sets ALLOWED_HOSTS, CORS_ALLOWED_HOSTS and CSRF_TRUSTED_ORIGINS together. Cannot contain a path, even for a subpath install. | https://paperless.example.com | source for PAPERLESS_URL |
PAPERLESS_CSRF_TRUSTED_ORIGINS | No | Comma-separated list of trusted origins for unsafe requests, required by Django 4+ to reach the admin over the web. Can be set via PAPERLESS_URL instead. | https://paperless.example.com | source for PAPERLESS_CSRF_TRUSTED_ORIGINS |
PAPERLESS_ALLOWED_HOSTS | No | Defaults to allowing all hosts. Should be set to the real domain before exposing the instance to the internet. | paperless.example.com | source for PAPERLESS_ALLOWED_HOSTS |
PAPERLESS_DBHOST | Yes | Hostname of the Postgres database, set alongside PAPERLESS_DBENGINE=postgresql in the official compose file. | db | source for PAPERLESS_DBHOST |
PAPERLESS_ALLAUTH_TRUSTED_PROXY_COUNT | No | Number of trusted proxy hops in X-Forwarded-For. Only trust this when untrusted clients cannot reach the app directly. | 1 | source for PAPERLESS_ALLAUTH_TRUSTED_PROXY_COUNT |
Volumes that must persist
| Path | What is in it | Source |
|---|---|---|
/usr/src/paperless/data (webserver) | Index, classification model and other application state that is not the documents themselves. | source for /usr/src/paperless/data |
/usr/src/paperless/media (webserver) | The actual stored documents, thumbnails and archive versions. The core data to back up. | source for /usr/src/paperless/media |
/var/lib/postgresql (db) | Postgres data directory backing the document index and metadata. | source for /var/lib/postgresql |
Behind a reverse proxy
- Set PAPERLESS_URL to the public address so ALLOWED_HOSTS, CORS_ALLOWED_HOSTS and CSRF_TRUSTED_ORIGINS all line up; a mismatch blocks logins with a CSRF error. source for this reverse-proxy note
- PAPERLESS_URL cannot include a path; use PAPERLESS_FORCE_SCRIPT_NAME instead to host Paperless under a subpath. source for this reverse-proxy note
- Set PAPERLESS_ALLOWED_HOSTS to the real domain before exposing the instance publicly; it defaults to allowing every host. source for this reverse-proxy note
What it needs alongside it
| Dependency | Why | Source |
|---|---|---|
| PostgreSQL 18 | Recommended production database, addressed through PAPERLESS_DBHOST and PAPERLESS_DBENGINE. | source for PostgreSQL 18 |
| Valkey (Redis-compatible) 9 | Message broker for the consumer task queue, set via PAPERLESS_REDIS. | source for Valkey (Redis-compatible) 9 |
Release timeline
| Version | Date | Breaking | What changed | Source |
|---|---|---|---|---|
v3.1.3 | 2026-09-04 | No | Bug fixes: header loading indicator on the tasks page, sidebar resize animation, dropdown word wrapping. | source for release v3.1.3 |
v3.1.2 | 2026-09-01 | No | Security fix for GHSA-2jhj-xqrq-rmrq, recommended for all users, plus dark mode select styling fixes. | source for release v3.1.2 |
v3.1.0 | 2026-08-27 | No | Adds an apply AI suggestions workflow action and support for selectively using remote OCR engines. | source for release v3.1.0 |
v3.0.2 | 2026-07-24 | Yes | Fixes a broken database migration shipped in 3.0.1 that could leave an upgrade partially applied. | source for release v3.0.2 |
v3.0.0 | 2026-07-22 | Yes | Major version with multiple breaking changes: removes API v1 and versions below 9, drops Python 3.10, removes document encryption and the pybzar barcode reader. | source for release v3.0.0 |
If it is not coming up
- ECONNREFUSED / ENOTFOUND / connection to server at "postgres" port 5432 failed
- Coolify volume data lost after redeploy / a new empty volume is created every deploy
- ERR_TOO_MANY_REDIRECTS — This page isn't working. your-domain.com redirected you too many times.
Read from the upstream documentation, repository and container registry by Keita Emsden on 2026-09-07. Every row links the page it came from. Upstream changes without telling anyone, so check the source link before you rely on a value.