readystack/paperlessngx repository overview

⁠Paperless-ngx

readystack/paperlessngx:v3.4.1-CE-ubuntu24.04-r1

Source, recipe and records

• Source and build recipe: https://readystack.dev/products/paperlessngx/recipe⁠
• Upstream source at this release's pinned commit (v3.4.1): https://github.com/paperless-ngx/paperless-ngx/tree/b67cfdf3fdfcde4883c4ac136c8545835f679d21⁠
• Product page: https://readystack.dev/products/paperlessngx⁠
• Hermetic Build Kit for this release (free with an account): https://readystack.dev/products/paperlessngx⁠
• Release history (JSON): https://readystack.dev/api/releases/paperlessngx⁠
• Defect record: https://readystack.dev/defects.html?product=paperlessngx⁠
• Today's scan: https://readystack.dev/products/paperlessngx#pp-grade⁠
• Report an issue: https://github.com/ReadyStackFree/readystack/issues/new?template=bug.yml&product=paperlessngx⁠
• Signing key (cosign): https://readystack.dev/keys/cosign.pub⁠

A cosign-signed build of github.com/paperless-ngx/paperless-ngx v3.4.1 (GPL-3.0-only), built clean-room from official upstream source by ReadyStack⁠.

⁠Who uses it and why

Who: Households, freelancers and small offices who want to scan their paper and find any document again later.

Why: Paperless-ngx turns scanned paper into a searchable online archive. It runs OCR on each document, files it with tags, correspondents and types it can learn to suggest, and keeps the data on your own server.

Use case: A household scans its letters, bills and contracts as they arrive. Paperless-ngx reads each scan, adds searchable text, tags it with the sender and document type, and stores it as an archival PDF beside the original; when a warranty is needed years later, a full-text search finds it.

About the upstream project, written from its own description: https://github.com/paperless-ngx/paperless-ngx⁠ · https://docs.paperless-ngx.com/⁠

⁠What you get

Signature, user and attestations below were measured on the published digest sha256:2fe11c61faf768fb097f1c553fba9b236d80a4596f756827528d6ff5a39c4feb on 2026-11-01.

• Scan scores — we scan every image we publish every day (an SBOM made with syft, vulnerabilities matched with grype, scored with cerodeo-v1, the rubric ce.rodeo published until 2026-10-26) and record each scan with how its score was derived. This release's first and latest scan: https://readystack.dev/products/paperlessngx⁠
• ReadyStack release check — passed at release on 2026-11-01: no fixable critical or high vulnerability (Docker Scout and OSV), a non-root user, SBOM and provenance attached. This is ReadyStack's own test, not a Docker grade; vulnerabilities published since then are in today's result at https://readystack.dev/queue⁠.
• Signed — cosign signature by the ReadyStack release key (fingerprint 04daa92344a52dbc) on this release's index digest sha256:2fe11c61faf768fb097f1c553fba9b236d80a4596f756827528d6ff5a39c4feb; verify with cosign verify --key https://readystack.dev/keys/cosign.pub readystack/paperlessngx:v3.4.1-CE-ubuntu24.04-r1.
• Attestations — An SPDX SBOM and SLSA v1 build provenance are attached to this digest.
• Runs as a non-root user (paperless).
• Built from source by ReadyStack.

⁠Which tag should I pull?

This image follows the ReadyStack release-tag convention:

• The current release is v3.4.1-CE-ubuntu24.04-r1 — the release listed at readystack.dev. Release tags use the pattern <upstream-version>-CE-<base-os>-r<N>; the current one is signed, attested (SBOM + provenance), and is provided under the ReadyStack Agreement⁠.

• Earlier release tags (an older version or revision in the same pattern) are superseded. They stay pullable so existing deployments can pin them, but they are no longer re-graded, and fixes appear only in newer releases: move to the current release. For a superseded release's build kit, ask support.

• Release tags never move, so pulling the same tag again never changes the image. To be offered each new release automatically (a new revision r<N+1>, or a new upstream version), use the ReadyStack Renovate preset: https://readystack.dev/updates.html⁠

• Any tag beginning with internal- is an engineering-pipeline artifact published for build observability. It is unsupported, may change or disappear without notice, and must not be used in production.

# ✓ current release
docker pull readystack/paperlessngx:v3.4.1-CE-ubuntu24.04-r1

# ✗ unsupported (do not pull)
docker pull readystack/paperlessngx:internal-...

This release is signed; verify it with cosign verify --key https://readystack.dev/keys/cosign.pub readystack/paperlessngx:v3.4.1-CE-ubuntu24.04-r1 (the signature is recorded in the public Sigstore transparency log). Support: [email protected]⁠, as set out in the ReadyStack Agreement⁠.

⁠Deployment

ONE product container (supervisord runs the granian ASGI webserver [:8000] + a Celery worker + Celery beat scheduler + the document consumer) PLUS two required datastore sidecars the customer provides: a PostgreSQL server and a Redis broker. NOT a single self-contained image — Paperless is multi-service. This lean CE image ships only English OCR (tesseract-ocr-eng); other languages need an image built with extra tesseract-ocr- packages, which the archive's offline rebuild does not do (it reproduces this English-only image).

Secrets go in env files that only you can read, not on the command line, and passwords that only set up the first start come out of them after setup. Create each file with install -m 600 /dev/null <file>, then write its lines into it with an editor, with your own values (a value typed into a shell stays in its history). Docker reads each line as written: no quotes around a value, no spaces around =.

paperlessngx-db.env:

# First start only: the postgres image reads POSTGRES_PASSWORD only when it initialises its empty volume. You can remove this line after the first start and recreate the db container; the database keeps the password.
POSTGRES_PASSWORD=YOUR_POSTGRES_PW

paperlessngx.env:

# The same database password as POSTGRES_PASSWORD; needed at every start.
PAPERLESS_DBPASS=YOUR_POSTGRES_PW
# Needed at every start; keep it unchanged once set.
PAPERLESS_SECRET_KEY=YOUR_LONG_RANDOM_SECRET
# First start only: the first start creates the superuser (PAPERLESS_ADMIN_USER) with PAPERLESS_ADMIN_PASSWORD. Remove this line after setup and recreate the container; the superuser keeps the password.
PAPERLESS_ADMIN_PASSWORD=YOUR_ADMIN_PW

docker network create paperless-net
docker run -d --name db --network paperless-net -e POSTGRES_DB=paperless -e POSTGRES_USER=paperless --env-file ./paperlessngx-db.env -v paperless-db:/var/lib/postgresql/data postgres:16
docker run -d --name redis --network paperless-net -v paperless-redis:/data redis:7-alpine
docker run -d --name paperlessngx --network paperless-net -p 8000:8000 -e PAPERLESS_DBHOST=db -e PAPERLESS_DBNAME=paperless -e PAPERLESS_DBUSER=paperless -e PAPERLESS_REDIS=redis://redis:6379 -e PAPERLESS_ADMIN_USER=admin --env-file ./paperlessngx.env -v paperless-data:/usr/src/paperless/data -v paperless-media:/usr/src/paperless/media readystack/paperlessngx:v3.4.1-CE-ubuntu24.04-r1

The three containers share the paperless-net network; db, redis and paperlessngx are the container names the backup, restore, export, password and token steps use. Use the same database password for POSTGRES_PASSWORD in paperlessngx-db.env and PAPERLESS_DBPASS in paperlessngx.env, and keep PAPERLESS_SECRET_KEY unchanged once set. The first start migrates the database and creates the superuser from PAPERLESS_ADMIN_USER and PAPERLESS_ADMIN_PASSWORD, which takes a few minutes; the sign-in page /accounts/login/ answers 200 afterwards. Then remove the PAPERLESS_ADMIN_PASSWORD line from paperlessngx.env and recreate the container on the same volumes (docker rm -f paperlessngx, then its docker run line again): the superuser keeps its password, which is then no longer in the container's environment (tested). The archive ships no Compose file.

⁠The full ReadyStack Hermetic Build Kit

The complete --network=none build kit for this image — plus admin/DB/API handbooks, the build's validation records, and its build provenance records — is a free download for any registered account at readystack.dev/products/paperlessngx⁠. A clean-room rebuild from this release's archive on an egress-blocked host reproduced its linux/amd64 digest sha256:85e31848a787e041c79a296adee5115eccd0ad800226cbe83e520e41584c1754 on 2026-11-01.

— ReadyStack · readystack.dev