selfhost
← All apps

Paperless-ngx

Archive and search documents with OCR, private PostgreSQL and Redis.

Choose your deployment and the way you want to use Selfhost. The instructions below follow that choice.

Set up Paperless-ngx

Complete local deployment with persistent dependencies

  • Choose the PostgreSQL and Redis stack. Select the initial administrator username and email; the generated ADMIN_PASSWORD initializes a fresh instance.
  • OCR defaults to English with one worker and one thread. Configure OCR languages and installed language packs to match your documents before importing a large collection.
Customize deployment inputs (4)
Local HTTP port port
portDefault: 8000
Initial hostname (change public URL later in app settings) hostname
hostnameDefault: "localhost"
Administrator username admin-user
identifierDefault: "admin"
Administrator email admin-email
emailDefault: "admin@example.com"

Save this as inputs.json and adjust the values before initialization. 

{
  "port": 8000,
  "hostname": "localhost",
  "admin-user": "admin",
  "admin-email": "admin@example.com"
}
selfhost app --directory ./paperless-ngx init paperless-ngx --method stack --inputs inputs.json

Initialization writes portable files and does not start the app. Review compose.yaml, the private .env and any files in files/, then start it: 

selfhost app --directory ./paperless-ngx start

No Selfhost dashboard or background service is needed. You can also start these files directly: 

cd paperless-ngx
docker compose -f compose.yaml up -d
  • Review the generated Compose and environment before starting. Only the app HTTP port is published, on loopback.
  • Keep credentials, database and data volumes together in an independent backup. Exported Compose files do not include volume data.
  • Sign in with the selected username and ADMIN_PASSWORD. Bootstrap settings do not reset an existing user.
  • Use Document export for portable backups, then copy the export volume elsewhere. OCR is enabled for English; choose additional languages explicitly.
  • Office document and email conversion require optional Tika/Gotenberg services. Add those only when needed and keep them private.

Before configuring integrations

  • Document export, sanity check, search optimization, reindexing, thumbnail regeneration and classifier training use Paperless native management commands. Exports are written into the persistent export volume.
  • OIDC connection writes structured django-allauth provider settings. Its callback ends in /accounts/oidc/selfhost/login/callback/. Password login remains enabled and new social accounts receive no automatic administrator role.
  • Native settings cover database, Redis, mail, file naming, consumption and optional Tika and Gotenberg endpoints. Recreate the service after applying environment changes.
  • Back up PostgreSQL, data, media, export and consume volumes together. A native document export is useful portability data, but is not a full configuration and database backup.
  • Database placement supports PostgreSQL and MariaDB. Version 3 uses PAPERLESS_DB_OPTIONS for TLS driver options; its older DBSSLMODE variables are no longer supported.
  • Tika and Gotenberg are optional external services; this deployment does not include them. Enable document conversion only after their endpoints are configured.
  • Social account linking and administrator assignment remain explicit Paperless account administration steps. No production OIDC browser round trip is implied by configuration tests.

Paperless-ngx integrations

Compose service: paperless-ngx. These operations use the profile saved when this deployment is created.

Native settings

Changes use the app’s Compose environment. Unrelated settings are preserved.

Supported fields (30)
Public URL public-url
string
Timezone timezone
string
OCR languages ocr-language
string
Additional OCR language packages ocr-languages-install
string · advanced
Document filename format filename
string
Watch subdirectories consume-recursive
stringChoices: true, false
Use subdirectories as tags consume-tags
stringChoices: true, false
Delete duplicate incoming files consumer-delete-duplicates
string · advancedChoices: true, false
Task worker count task-workers
string
Threads per worker worker-threads
string
Database host database-host
string · advanced
Database name database-name
string · advanced
Database username database-user
string · advanced
Database password database-password
secret · advanced
Redis URL redis
secret · advanced
Allow local signups signup
stringChoices: true, false
Allow IdP signups social-signup
stringChoices: true, false
Identity provider configuration (JSON) social-config
secret · advanced
Authentication provider modules social-apps
string · advanced
Disable local login disable-local-login
string · advancedChoices: true, false
Enable Tika/Gotenberg conversion tika
string · advancedChoices: true, false
Tika endpoint tika-url
string · advanced
Gotenberg endpoint gotenberg-url
string · advanced
SMTP host smtp-host
string
SMTP user smtp-user
string
SMTP password smtp-password
secret
SMTP STARTTLS smtp-tls
stringChoices: true, false
Sender address smtp-from
string
Database driver options database-options
Version 3 native options, for example sslmode=verify-full,sslrootcert=/certs/ca.pem. Mount any referenced certificate separately. string · advanced
Database engine database-engine
string · advancedChoices: sqlite, postgresql, mariadb

Save a JSON map of the field IDs you want to change as changes.json. Replace FIELD_ID with an ID from the supported fields above, and use its declared value type. Review the plan and replace REVIEWED_REVISION with the revision it returns. 

{
  "FIELD_ID": "YOUR_VALUE"
}
selfhost app --directory ./paperless-ngx config paperless-ngx
selfhost app --directory ./paperless-ngx plan paperless-ngx changes.json
selfhost app --directory ./paperless-ngx apply paperless-ngx changes.json --revision REVIEWED_REVISION

Saved changes need service recreation to become active. Existing interpolated environment values stay under your control in .env or Compose.

Identity provider login

Selfhost can register a client with a supported provider and configure this app. Callback path: /accounts/oidc/selfhost/login/callback/.

No administrator role is assigned by Selfhost. Check the app’s first-login policy and retain a local recovery account.

Save connection.json and replace the URLs. Supply SELFHOST_IDP_TOKEN privately in your shell. 

{
  "provider": "zitadel",
  "issuer": "https://identity.example.com",
  "app_url": "https://app.example.com",
  "name": "Paperless-ngx"
}
selfhost app --directory ./paperless-ngx connect-account paperless-ngx connection.json
selfhost app --directory ./paperless-ngx connect-plan paperless-ngx connection.json
selfhost app --directory ./paperless-ngx connect paperless-ngx connection.json --revision REVIEWED_REVISION

Test sign-in in a separate browser session. HTTPS domains and HTTP loopback development origins are supported by Selfhost; the chosen app and provider must also accept the resulting callback. Provider permissions, localhost and recovery.

Database placement

This recipe supports postgres, mariadb. Workspace projects can choose a dedicated database, a shared source with a separate database and account, or an existing external database before their first start.

  • postgres adapter TLS modes: disable, require, verify-full. Use a private network for connections with TLS disabled.
  • mariadb adapter TLS modes: disable, require, verify-full. Use a private network for connections with TLS disabled.

Standalone directories use the generated Compose and environment files directly. Configure the database there before first start. Selfhost’s source provisioning commands belong to workspace projects and are optional.

Database setup, CLI commands and backups

App actions

Export documents and database · schedulable

Create a portable archive in the persistent export volume. Copy it off this host for disaster recovery.

selfhost app --directory ./paperless-ngx action paperless-ngx export-documents

A workspace can schedule this workflow while Selfhost runs. A standalone user can invoke it through an external scheduler. Scheduling guide.

Check document storage · schedulable

Check database and stored-file consistency without deleting files.

selfhost app --directory ./paperless-ngx action paperless-ngx sanity-check

A workspace can schedule this workflow while Selfhost runs. A standalone user can invoke it through an external scheduler. Scheduling guide.

Optimize search index · schedulable

Optimize the existing search index.

selfhost app --directory ./paperless-ngx action paperless-ngx optimize-index

A workspace can schedule this workflow while Selfhost runs. A standalone user can invoke it through an external scheduler. Scheduling guide.

Rebuild search index

Rebuild the full-text index when needed.

selfhost app --directory ./paperless-ngx action paperless-ngx rebuild-index
Apply filename format

Rename stored document files using the current filename format. Back up the document store first.

selfhost app --directory ./paperless-ngx action paperless-ngx rename-documents
Train automatic document matcher · schedulable

Train the classifier using existing document assignments.

selfhost app --directory ./paperless-ngx action paperless-ngx train-matcher

A workspace can schedule this workflow while Selfhost runs. A standalone user can invoke it through an external scheduler. Scheduling guide.

Rebuild thumbnails

Regenerate document thumbnails; may take a long time.

selfhost app --directory ./paperless-ngx action paperless-ngx rebuild-thumbnails

App configuration reference

Versions and updates

This deployment uses the following images. Existing projects retain their saved recipe and images. A new catalogue version does not silently update them.

  • database: postgres:17-alpine
  • redis: redis:8.2.2-alpine
  • paperless-ngx: ghcr.io/paperless-ngx/paperless-ngx:3.2.1
  • 3.2.1 ghcr.io/paperless-ngx/paperless-ngx:3.2.1

    Local PostgreSQL backend was asserted at runtime. Selected administrator login, PDF consumption, native document export manifest, sanity check, index optimization, environment changes and persistent recreation passed. Alternate MariaDB and OIDC bindings are source-audited.

Review compatibility and back up app data before an update. Choose an image version and review the change.

Keep control of your setup

Selfhost remains optional. Your app runs using ordinary Compose files, its own settings and persistent data. Keep the Compose project name and volumes to preserve storage. Configuration exports and setting backups do not include application data.

Standalone CLI guide · Backups and removal · Paperless-ngx documentation

Built by Obiente. Your services, your configuration.

Licensed under AGPL-3.0-or-later.