Deploy paperless-ngx

Deploy and Host paperless-ngx on Railway

paperless-ngx is an open-source document management system that turns your physical and digital paperwork into a searchable online archive. It scans, OCRs, and indexes documents, then automatically tags and sorts them by correspondent, type, and date, so you can find any receipt, contract, or letter in seconds.

About Hosting paperless-ngx

Hosting paperless-ngx involves running several cooperating services: the Django web application and its background workers, a PostgreSQL database for metadata, Redis for the task queue, and optionally Apache Tika and Gotenberg for parsing Office files and emails. Documents, thumbnails, and the search index must live on persistent storage so nothing is lost between deploys. You also need to set a secret key, configure the public URL and allowed hosts, and wire the services together over a private network. This template provisions and connects all of these for you, with sensible defaults and persistent volumes already in place.

Common Use Cases

• Going paperless at home: scan bills, tax documents, warranties, and medical records into a private, searchable archive
• Small business record-keeping: centralize invoices, receipts, and contracts with automatic tagging and full-text search
• Email archiving: pull attachments and messages from IMAP mailboxes and file them automatically using mail rules
• Replacing filing cabinets for freelancers, landlords, and households who need quick access to documents on any device

Dependencies for paperless-ngx Hosting

Dependencies for paperless-ngx Hosting

• PostgreSQL: stores document metadata, tags, users, and settings
• Redis: message broker for background tasks such as OCR and document consumption
• Apache Tika: extracts text and metadata from Office documents and emails
• Gotenberg: converts Office documents and emails to PDF for archiving

Implementation Details

Mandatory setup

Adding documents. Railway has no shared network folder, so the consumption directory is not directly reachable from your computer. Upload documents through the web interface (drag and drop), the REST API, a mobile app such as Paperless Mobile, or by configuring mail accounts in the admin panel. Storage. Documents and the search index are stored on a Railway volume mounted at the paths set in PAPERLESS_MEDIA_ROOT and PAPERLESS_DATA_DIR. Monitor volume usage as your archive grows, and use the built-in document exporter for regular off-platform backups. OCR language. OCR defaults to English. To recognize other languages, set PAPERLESS_OCR_LANGUAGE (e.g. eng+deu+ita for English, German and Italian) or change the option in the settings.

Optional setup

Creating your admin account. Add these variables to the paperless-ngx service to create a superuser on first boot (no need to remove them after your first deploy):

PAPERLESS_ADMIN_USER=admin
PAPERLESS_ADMIN_PASSWORD=choose-a-strong-password

Custom domain. If you attach a custom domain, update PAPERLESS_URL (e.g. https://docs.example.com). You have further control on hosts and CORS by setting:

• PAPERLESS_ALLOWED_HOSTS (comma-separated list): you really should set this value to the domain name you're using. Failing to do so leaves you open to HTTP host header attacks. When PAPERLESS_URL is set (as does this template), its value is combined with this variable's value.
• PAPERLESS_CORS_ALLOWED_HOSTS (comma-separated list): list of allowed hosts that can do CORS calls. Set this to your public domain name. When PAPERLESS_URL is set (as does this template), its value is combined with this variable's value.

The full list of available configuration variables is available in the official docs.

Tips for Getting the Most out of paperless-ngx

• Let the matching algorithm learn. Correspondents, tags and document types default to the Auto matching algorithm, which trains on your existing documents. Manually classify your first few dozen documents and accuracy improves quickly. You can also use exact, regex or fuzzy matching rules. See matching.
• Automate with workflows. Workflows can assign owners, tags, custom fields and permissions when documents are added or updated, or send webhooks/emails. See workflows.
• Use custom fields and saved views. Track things like invoice amounts, due dates or warranty expiry with custom fields, and pin saved views (e.g. "Inbox", "Unpaid invoices") to the dashboard.
• Barcodes and ASNs. Print archive serial number (ASN) labels to link paper originals to their digital copies, and use barcode separator pages to split batch scans. Enable with PAPERLESS_CONSUMER_ENABLE_BARCODES and PAPERLESS_CONSUMER_ENABLE_ASN_BARCODE. See barcodes.
• Scanner workflow. Since there is no network share, configure your scanner (or a scanning app) to email scans to a dedicated mailbox, then let a mail rule import them automatically.
• API tokens. Generate a personal API token from your profile for scripts, mobile apps and integrations instead of using your password.

Backups and Maintenance

• Export regularly. Use the built-in document exporter for portable, version-independent backups of documents and metadata. Connect to the service with the Railway CLI (railway ssh) and run document_exporter <path-on-volume>/export --zip, then copy the archive off-platform. A volume snapshot alone is not a substitute: keep at least one copy outside Railway.
• Back up the database too. Railway's PostgreSQL service has its own volume; enable backups for it, or rely on the exporter, which includes all metadata.
• Upgrading. Database migrations run automatically on startup. Before pulling a new paperless-ngx image, read the changelog and take an export. Pinning a major version tag (e.g. ghcr.io/paperless-ngx/paperless-ngx:2) avoids surprise breaking upgrades. Upgrading PostgreSQL across major versions requires a dump and restore.
• Housekeeping commands. If search results seem out of date, run document_index reindex; to check for missing or corrupted files, run document_sanity_checker. All management commands are documented in the administration guide.
• Redis is disposable. It only holds the task queue, so losing its data doesn't affect your archive; at worst, in-progress tasks need to be re-uploaded.

Further Reading

• paperless-ngx usage overview
• paperless-ngx advanced usage
• paperless-ngx FAQ and troubleshooting
• Apache Tika server documentation
• Gotenberg configuration
• PostgreSQL documentation
• Redis documentation

Why Deploy paperless-ngx on Railway?

Railway is a singular platform to deploy your infrastructure stack. Railway will host your infrastructure so you don't have to deal with configuration, while allowing you to vertically and horizontally scale it.

By deploying paperless-ngx on Railway, you are one step closer to supporting a complete full-stack application with minimal burden. Host your servers, databases, AI agents, and more on Railway.