Submit

File Storage guide

Paperless-ngx Docker Compose: Import Documents and Prove Recovery

Deploy Paperless-ngx from current Compose files, protect signing secrets, validate document imports, and restore an export into an empty test instance.

Published and reviewed by OpenAlt · October 7, 2026

Stacks of old documents and papers piled on dusty shelves, creating an organized yet chaotic scene.
Photo by Muhammad Jawadur Rahman on Pexels

Install Paperless-ngx from its current official Compose files, keep the first session private, and prove that an exported collection restores correctly before trusting it with important documents. The useful outcome is a searchable, recoverable archive—not simply a web interface that accepts a PDF.

This guide follows upstream documentation checked on October 7, 2026. It concerns document archiving, not replacing a collaborative team wiki. Keep original files and any necessary physical records until you have independently verified the archive and its recovery process.

Table of contents

What should you decide before importing documents?

Choose who may read the archive, who maintains it, and how you recover without the original server. Scanned documents can become more sensitive and easier to search than the paper pile they replace.

The OpenAlt Paperless-ngx entry helps establish the product's role and upstream project. Use a document archive when the job is importing, classifying and retrieving files. A shared filesystem or collaborative editor may solve a different need without adding an OCR pipeline.

The official setup guide recommends PostgreSQL for new installations and provides templates for several arrangements. Pick a supported route rather than combining fragments from unrelated NAS tutorials. Identify the host, data locations, administrator and backup destination in a short operating note.

Start with nonsensitive documents you can afford to lose during experimentation. Define success before importing everything: readable originals, useful search results, correct access permissions, and a demonstrated restore. If nobody can maintain the database and application, reconsider the hosting arrangement before the archive becomes essential.

Which Compose files should you use?

Download the Compose definition and its accompanying environment files together. A YAML file copied without its companion configuration is an incomplete installation.

For a fresh project directory, the current PostgreSQL route is:

mkdir paperless-archive
cd paperless-archive
curl -fL -o docker-compose.yml https://raw.githubusercontent.com/paperless-ngx/paperless-ngx/main/docker/compose/docker-compose.postgres.yml
curl -fL -o docker-compose.env https://raw.githubusercontent.com/paperless-ngx/paperless-ngx/main/docker/compose/docker-compose.env
curl -fL -o .env https://raw.githubusercontent.com/paperless-ngx/paperless-ngx/main/docker/compose/.env

Read the downloaded files before running them. The official template checked for this guide defines three services: webserver, db and broker. At this date it uses PostgreSQL 18, Valkey 9, and the Paperless-ngx project image.

That is a dated description of the template, not a permanent promise about the moving main branch. Keep the reviewed files with your operating notes and record the image versions used by your installation.

Pay attention to volume paths. The current PostgreSQL template mounts its data at /var/lib/postgresql; do not transplant a mount from an older database major version without reviewing its requirements. For existing installations, treat any database-major change as a separate migration.

What must you configure before startup?

Set unique secrets, confirm storage locations, and restrict the initial web port before starting the stack. Default examples are starting material, not a completed private deployment.

Edit these settings deliberately:

  • Replace the database service's example POSTGRES_PASSWORD with a unique value, and set PAPERLESS_DBPASS in docker-compose.env to the same value.
  • Generate a separate application signing key and set PAPERLESS_SECRET_KEY in docker-compose.env.
  • Change the published web port to 127.0.0.1:8000:8000 for the private trial.
  • Confirm the consumption and export host directories, plus ownership needed by the application.
  • Keep both environment files and the Compose definition out of public repositories when they contain secrets.

The configuration reference says PAPERLESS_SECRET_KEY is required. Generate a value locally with openssl rand -hex 32; do not reuse a database password as the signing key. Protect the resulting configuration through your normal secret-storage process.

Validate without printing resolved secrets using docker compose config -q, then run docker compose pull and docker compose up -d. Docker documents the quiet validation option in its Compose config reference. Inspect startup logs and open the private address from the host or an SSH tunnel.

Detailed sepia close-up of a binder filled with documents, emphasizing texture.
Photo by Joachim Schnürle on Pexels
Neatly arranged blue office binders labeled with dates and names for organized storage.
Photo by Zulfugar Karimov on Pexels

How do you verify the first import?

Create the first administrator privately, then test a small collection with known contents. An import is successful when the original remains readable and expected text can be found—not merely when a task disappears from the queue.

The setup instructions describe creating the superuser on the first web visit. Complete this before granting network access to other people. Use a separate ordinary account to test the daily experience afterward.

Try a digitally generated PDF, a clear scan and a document with a layout similar to your real paperwork. These are suggested acceptance samples, not a claim that a particular OCR accuracy has been measured here.

For each sample, verify the downloaded original, page order, orientation, recognized text and searchability. Check the assigned document type, correspondent and tags. Review mistakes manually before teaching an automated rule to repeat them across the archive.

A successful upload does not establish a useful classification policy. Write down which fields you actually search by and keep the first tagging system small. Add complexity only when it solves a retrieval problem you have encountered.

How should ingestion and permissions work?

Treat the ingestion route and the reader's permissions as separate decisions. Being able to place a file into an import directory does not tell you who should be allowed to read it afterward.

The configuration reference documents the consumption directory, user mapping and public URL settings. If you later use a reverse proxy, set PAPERLESS_URL to the intended external origin and verify authentication through that exact address.

Start with manual uploads. Add a scanner drop folder or email ingestion only after its behavior is clear. Use a dedicated ingestion destination so the application is not watching your only original-file archive. Preserve originals independently until you trust both ingestion and recovery.

Check access from an ordinary user and a signed-out browser. Test a sensitive sample separately from a shared sample; a broad shared account makes meaningful access review much harder.

The Nextcloud deployment guide covers the different job of file synchronization and collaboration. If both systems handle documents, define which one holds originals and how files enter Paperless. Avoid two automated processes moving or deleting the same files without an explicit ownership rule.

How do you export and restore the archive?

Create an application export, copy it off the host, and import it into a completely separate empty installation. Match the Paperless version for the recovery drill.

With the official service and export mount names, run:

docker compose exec -T webserver document_exporter ../export

The administration guide describes an export containing documents and application metadata, and explains that API tokens are excluded. Plan to regenerate those tokens and reconnect their consumers after recovery.

Pause ingestion while establishing a coherent backup. Check the export command's exit status and inspect the output. Keep protected copies of the deployment configuration and required secrets separately. An export left in ./export on the same disk is convenient, but not an independent recovery copy.

For the drill, create another project directory with fresh data volumes and a different loopback port. Copy the completed export into that project's export directory. Confirm you are operating on the empty test installation, then run there:

docker compose exec -T webserver document_importer ../export

The importer is intended for an empty installation; do not use production as the rehearsal target. Verify document counts, representative originals, search results, users and permissions after import. Recreate integrations with new tokens and test them independently.

Estimate retained copies with the backup storage calculator. Record the measured restoration time and the backup location another authorized operator would use. An export becomes a trusted backup only after you demonstrate recovery from it.

How should updates be handled?

Update the application and its dependencies deliberately, with a tested backup and a known previous version. Avoid letting a copied current template silently upgrade every component at once.

The official Compose template uses a moving application tag. Record the resolved image you have tested and review release notes before a later pull. Treat changes to PostgreSQL storage layout or major version as their own operation.

Rehearse on a restored copy, then check import, search, downloads, permissions and export after the production update. If rollback is needed, use the matching old software and pre-update data rather than assuming old code understands a newer database schema.

Keep the operating note brief but complete: versions, storage paths, last successful export, last successful restore and responsible person. That is the handoff another operator needs when the original installer is unavailable.

FAQ

Is the consumption directory my backup?

No. It is an ingestion location. Protect originals and completed exports independently.

Will exported API tokens work after recovery?

The exporter excludes API tokens. Regenerate them and update the integrations that use them.

Does a shared import folder establish document permissions?

No. Test the application's resulting access rules separately with ordinary accounts.

Can I copy a newer Compose file over my existing stack?

Review every image and volume change first. A newer template may contain a database-major change that requires a separate migration.