Paperless-ngx

Upstream source: Current installation guide. Paperless needs a Redis-compatible broker for background work. PostgreSQL stores document metadata; the Service volumes keep its index and document files. OCR of Office documents is an optional later Tika/Gotenberg addition.

Towbar manifests

# .towbar/datastores/paperless-ngx-postgres.datastore.yml
id: paperless-ngx-postgres
name: Paperless-ngx PostgreSQL
type: postgres
container:
  network: application
  networkAlias: paperless-ngx-postgres
  resources:
    cpus: 1
    memory: 1g
secrets:
  runtime:
    - POSTGRES_USER
    - POSTGRES_DB
    - POSTGRES_PASSWORD
environments:
  production:
    server: 192.0.2.10

# .towbar/datastores/paperless-ngx-redis.datastore.yml
id: paperless-ngx-redis
name: Paperless-ngx Redis
type: redis
container:
  network: application
  networkAlias: paperless-ngx-redis
  resources:
    cpus: 0.5
    memory: 512m
secrets:
  runtime:
    - REDIS_PASSWORD
environments:
  production:
    server: 192.0.2.10

# .towbar/services/paperless-ngx.service.yml
id: paperless-ngx
name: Paperless-ngx
buildServer: null
deployment:
  type: image
  image: ghcr.io/paperless-ngx/paperless-ngx:2.18.4
container:
  port: 8000
  network: application
  volumes:
    - name: data
      mountPath: /usr/src/paperless/data
      initialData: image
    - name: media
      mountPath: /usr/src/paperless/media
      initialData: image
    - name: consume
      mountPath: /usr/src/paperless/consume
      initialData: image
environments:
  production:
    server: 192.0.2.10
rollout:
  type: recreate
  maintenanceMode: true
  reason: Persistent application data uses a single writer
secrets:
  runtime:
    - PAPERLESS_REDIS
    - PAPERLESS_DBENGINE
    - PAPERLESS_DBHOST
    - PAPERLESS_DBNAME
    - PAPERLESS_DBUSER
    - PAPERLESS_DBPASS
    - PAPERLESS_SECRET_KEY
    - PAPERLESS_URL
domains:
  primary: paperless-ngx.example.com
tls:
  mode: direct

Configure

Prepare the example server, connect the repository, and map production to the branch containing these manifests. Replace the example server IP and domain. Commit the manifests, then sync the repository and inspect the resolved configuration.
Save the initialization values in the table below for the postgres Datastore and the redis Datastore under Datastore → Settings → Secrets. Deploy them first and wait for readiness. These values create the database and user only on an empty volume.
Set the Service’s declared runtime values under Service → Settings → Secrets using the table below. Replace descriptions and placeholders with actual values; do not commit passwords or keys.
Keep the Service’s named volumes attached across deployments. Towbar’s Datastore backup policy does not back up Service volumes, so include them in your own recovery plan.
Deploy the Service, then perform the checks below before enabling auto-deploy.

Datastore values

Save these in each Datastore’s Settings → Secrets before deploying it. Use the suggested names or choose your own, then use the same names and passwords in the Service connection values below.

Datastore	Key	Suggested value
Paperless-ngx postgres	`POSTGRES_DB`	paperless_ngx
Paperless-ngx postgres	`POSTGRES_USER`	paperless_ngx
Paperless-ngx postgres	`POSTGRES_PASSWORD`	Run `openssl rand -hex 32`; save its output and reuse it in the Service connection value.
Paperless-ngx redis	`REDIS_PASSWORD`	Run `openssl rand -hex 32`; save its output and use it in the Service broker URL.

Runtime values

Save these values on the Service after the repository sync. The manifest declares required keys, not their values.

Key	Value to save
`PAPERLESS_REDIS`	`redis://:PASSWORD@paperless-ngx-redis:6379/0` (replace `PASSWORD` with `REDIS_PASSWORD`)
`PAPERLESS_DBENGINE`	postgresql
`PAPERLESS_DBHOST`	paperless-ngx-postgres
`PAPERLESS_DBNAME`	Same value as POSTGRES_DB.
`PAPERLESS_DBUSER`	Same value as POSTGRES_USER.
`PAPERLESS_DBPASS`	Same value as POSTGRES_PASSWORD.
`PAPERLESS_SECRET_KEY`	Generate a long random key.
`PAPERLESS_URL`	https://paperless-ngx.example.com

Verify

Upload a PDF and wait for processing. Confirm the document and its searchable text remain after redeployment. Back up both PostgreSQL and the Service volumes together. For field constraints, see Service manifest and Datastore manifest.

Start here

Open-source software

Service recipes

Datastore recipes

Complete stacks

Towbar manifests

Configure

Datastore values

Runtime values

Verify

​Towbar manifests

​Configure

​Datastore values

​Runtime values

​Verify

Towbar manifests

Configure

Datastore values

Runtime values

Verify