Deploy Paperless-ngx Workflows

Deploy and Host self hosted Paperless-ngx Workflows (Open-Source Document Workflow Automation) on Railway

Deploys Paperless-ngx 3.3.0 with Postgres and Redis. Workflows auto-title with {{correspondent}} and {{created_year}}, assign tags, and fire webhooks via Document Added or Scheduled triggers.

About Hosting Paperless-ngx Workflows open-source software on Railway (self hosted Paperless-ngx workflow template)

Your templates, tags, and workflow rules stay in the volume next to the OCR text. You just write the actions and watch the pipeline file documents.

Why Deploy Paperless-ngx Workflows, the Google Drive alternative on Railway (Railway Free Trial)

Google Drive won't auto-title invoices or fire reminder webhooks; you'll do that by hand. Paperless-ngx Workflows costs nothing for software and you own the data.

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 Workflows 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.

Railway vs Other Hosting Providers and VPS for Paperless-ngx Workflows self hosting

Railway gives you the Paperless-ngx, Postgres, and Redis stack wired together, while a raw VPS leaves you to assemble it.

Common Use Cases for hosted Paperless-ngx Workflows

• Auto-title by source: A Document Added trigger matches your bank's PDFs, then an Assignment action renames them to "{{correspondent}} {{created_year}}-{{created_month}} Statement" and applies the Bank tag.
• Owner from mail rule: A Consumption Started trigger filtered to the Invoices mail rule assigns owner and tags before OCR finishes, so finance gets them right away.
• Contract reminders: A Scheduled trigger fires 30 days before a date custom field via negative offset, posting {{doc_url}} and {{doc_id}} to a webhook that creates a task.
• Invoice handoff: Every new invoice matching a content filter posts a JSON webhook with {{doc_url}} to n8n or your accounting tool.
• Tag cleanup: A Document Updated trigger removes a "needs-review" tag when the storage path changes to /archive/.

Dependencies for Paperless-ngx Workflows Docker hosted on Railway

The stack needs paperless-ngx, Postgres, and Redis. Railway sets PAPERLESS_SECRET_KEY, admin credentials, PAPERLESS_URL, and DB/Redis connection vars.

Deployment Dependencies for Managed Paperless-ngx Workflows Service (Document Workflows)

You need three services. The template sets PAPERLESS_DBENGINE=postgresql plus DBHOST, DBPORT, DBNAME, DBUSER, DBPASS, and PAPERLESS_REDIS. PAPERLESS_OCR_LANGUAGE=eng and PAPERLESS_TIME_ZONE=UTC control OCR defaults.

Implementation Details for Paperless-ngx Workflows (Using Paperless-ngx official docker image)

The container runs the official paperless-ngx image tagged 3.3.0. Port 8000 sits behind Railway's proxy. PAPERLESS_URL uses the public HTTPS domain for CSRF and webhooks. Secrets come from ${{secret()}}.

How does Paperless-ngx Workflows compare against other document management systems with automation

Paperless-ngx vs Mayan EDMS

• Simplicity: Paperless' trigger/action rows are easier to reason about than Mayan's deeper workflow engine.
• Enterprise metadata: Mayan wins for formal cabinets and granular permissions; Paperless keeps tags, correspondents, and custom fields smaller.
• Workflow depth: Mayan models multi-step review states; Paperless is a one-pass pipeline with Assignment, Removal, Email, Webhook, and Move to Trash.

Paperless-ngx vs Docspell

• Automation style: Docspell's rule engine handles source and email rules well; Paperless shows the same logic in trigger and action lists.
• Community: Paperless has more users and examples for title templates like {{correspondent}} {{created_year}}.
• Email intake: Docspell's mail collector wins if email is your only source; Paperless needs an IMAP rule plus a workflow to match.

Paperless-ngx vs Papermerge

• Folder model: Papermerge wins if you want a folder tree; Paperless is tag-first and workflows act on metadata, not folder moves.
• Automation: Papermerge offers simpler matching rules; Paperless adds Scheduled triggers and Webhook actions.
• OCR output: Both extract text, but Paperless adds PDF/A archive copies and keeps workflow automation in active development.

Paperless-ngx vs Google Drive

• Self hosting: Paperless is GPL-3.0 and runs in your Railway project; Drive is closed SaaS.
• Automation: Drive needs Apps Script for upload reactions; Paperless has native triggers for Consumption Started, Document Added, Updated, and Scheduled.
• Data control: Paperless keeps documents, tags, and webhook payloads in your stack; Drive's OCR and metadata stay in Google's system.

How to use Paperless-ngx Workflows (the OSS document workflow automation)?

1. Log in with PAPERLESS_ADMIN_USER and the generated PAPERLESS_ADMIN_PASSWORD from Railway variables.
2. Create tags, correspondents and a date custom field for reminders.
3. Open Workflows and add a Document Added trigger with a content match like "invoice".
4. Add an Assignment action: title template {{correspondent}} {{created_year}}, tags, and the custom field.
5. Add a Webhook action posting {{doc_url}} and {{doc_id}} as JSON.
6. Set the sort order so assignment runs before the webhook.
7. Upload a test PDF and check the title, tags and webhook log.
8. Add a Scheduled trigger on the custom field with a negative day offset for reminders.

How to self host Paperless-ngx Workflows on other VPS Services (Paperless-ngx self hosting guide)

Clone the Repository

Get the source for config examples and docs:

git clone https://github.com/paperless-ngx/paperless-ngx.git
cd paperless-ngx

You do not need to build from source; the official Docker image is what we will run.

Install Dependencies

Install Docker and the Compose plugin on your VPS. On Debian or Ubuntu:

sudo apt update && sudo apt install docker.io docker-compose-plugin

Paperless also needs Postgres and Redis, which the sample compose file includes as services.

Configure Environment Variables

Copy docker/compose/docker-compose.postgres.yml to your working directory with docker-compose.env from the same folder, and set at least:

PAPERLESS_SECRET_KEY=change-me-to-a-long-random-string
PAPERLESS_ADMIN_USER=admin
PAPERLESS_ADMIN_PASSWORD=change-me
PAPERLESS_URL=https://your-domain
PAPERLESS_TIME_ZONE=UTC
PAPERLESS_OCR_LANGUAGE=eng

For workflow webhooks to generate valid doc links, PAPERLESS_URL must match your public domain exactly.

Start the Paperless-ngx Workflows Application

Launch the stack:

docker compose -f docker-compose.postgres.yml up -d

Then open your-domain and log in with the admin credentials you set. Railway handles the volume, database, Redis, and public URL for you when you use the template.

Official Pricing of Paperless-ngx Workflows (Paperless-ngx pricing)

Paperless-ngx Workflows is part of the GPL-3.0 Paperless-ngx project, so the software itself is free with no license fees or premium tiers.

Paperless-ngx Workflows cloud vs self hosted comparison (Pricing, features, costs, and more)

There's no official Paperless-ngx cloud, so the real comparison is self-hosting on Railway versus a third-party host.

Monthly cost of self hosting Paperless-ngx Workflows on Railway

Expect about $5-15 per month for a small personal archive on Railway, covering the Paperless-ngx container, Postgres, Redis, and a volume. The $5 Railway trial lets you test workflows before paying.

System Requirements for Hosting Paperless-ngx Workflows on a VPS

Paperless-ngx runs on a Raspberry Pi, but OCR is slow on weak CPUs. Docker Compose is the recommended deployment method, so any VPS with Docker works.

Frequently Asked Questions (FAQs)

Why did my workflow not run?

Check the trigger. Consumption Started cannot see tags, correspondents, or content, so a content filter there never matches. Also confirm sort order and that Move to Trash did not abort the pipeline earlier.

What is the difference between Consumption Started and Document Added triggers?

Consumption Started fires before OCR and matching; only source, file name, path, or mail rule are known. Document Added fires after matching, so tags, correspondents, and created-date placeholders are available.

Can workflows send email on Railway?

Only if you set PAPERLESS_EMAIL_* yourself. Railway blocks outbound SMTP below Pro, so Email actions usually fail. Use a webhook to a mail service instead.

Can a webhook reach another Railway service?

Yes, using the target's private Railway domain. Internal requests are allowed by default; set PAPERLESS_WEBHOOKS_ALLOW_INTERNAL_REQUESTS=false to block them.

What happens when several workflows match one document?

They run sequentially by sort order. Later assignments override earlier single-value assignments like correspondent or owner; multi-value tags and custom fields merge.

Who can edit workflows?

Workflows have no owner. Anyone with edit permission sees and modifies all workflows, and workflows can change document permissions, so restrict that permission to admins.