Deploy and Host self hosted Paperless-ngx API (Open-Source Document Management API) on Railway

This template deploys Paperless-ngx with Postgres and Redis on Railway, exposing the REST API at https://your-domain/api/. Create a token in the web UI, then post scans from scripts, n8n, or cron into your self-hosted archive.

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

Your documents stay yours: OCR text, PDF/A archives, tags, and search data live in the Postgres database and the mounted volume inside this stack. The admin credentials and generated secret key are stored in Railway variables, not baked into the image. You still control users, permissions, and tokens from the UI.

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

You own the data and the token, not a per-user SaaS bill. Google Drive stores files but does not run OCR, tags, or accept a curl upload from a cron job without extra services. Railway's $5 trial covers a small archive while you prove the scripted intake loop.

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 API 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 API self hosting

Railway gives you the managed stack, while other providers leave you to assemble it. | Provider | What You Get with Railway | What You Get with the Other Provider | | DigitalOcean | One-click template, managed Postgres and Redis, persistent volume, public URL | A droplet you must provision, secure, and maintain with Docker Compose | | AWS | Same managed services without IAM and networking overhead | EC2 or ECS with more control but hours of setup and configuration | | Hetzner | No server administration, automatic backups, easy scaling | Cheap raw compute, but you run Postgres, Redis, and the app manually | That still works.

Common Use Cases for hosted Paperless-ngx API

Scanner or phone shortcut: A mobile shortcut posts a photo or scan directly to POST /api/documents/post_document/, so a receipt lands in Paperless-ngx before you pocket the phone.
n8n email attachments: An n8n workflow watches an inbox, saves each PDF attachment, then uploads it with a correspondent id and tag id set from the sender.
Nightly bank statements: A cron job downloads monthly PDFs from your bank, sends them to the API with a tag for the account, and lets OCR and matching run in the background.
Search from another app: A dashboard or browser extension calls GET /api/documents/?query=insurance and returns matches without anyone opening the Paperless-ngx UI.
Bulk retagging: A script lists documents matching an old tag, then POSTs to /api/documents/bulk_edit/ to move them to a new correspondent or tag set.

Dependencies for Paperless-ngx API Docker hosted on Railway

The Railway template runs Paperless-ngx 3.3.0 with Postgres and Redis so scripted uploads stay responsive while OCR runs. No extra packages; Railway injects the generated secret key, admin password, and database credentials, and a persistent volume holds your data, media, and consume directory.

Deployment Dependencies for Managed Paperless-ngx API Service (Document Management)

The stack runs paperless-ngx on port 8000 with volume /usr/src/paperless/data, Postgres, and Redis as the Celery broker. Secrets use ${{secret()}}.

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

The template pulls ghcr.io/paperless-ngx/paperless-ngx:3.3.0. API tokens are created per user in My Profile and sent as Authorization: Token your-token. Set PAPERLESS_URL to Railway domain. Uploads to /api/documents/post_document/ return a task UUID; Redis queues OCR. Use a dedicated automation user, keep PAPERLESS_ADMIN_PASSWORD in Railway variables.

How does Paperless-ngx API compare against other document management systems

Paperless-ngx vs Mayan EDMS (Mayan EDMS Alternative)

API simplicity: Token auth plus post_document scripts easily; Mayan needs more setup.
Resource use: Tesseract OCR fits modest VPS specs; Mayan prefers heavier CPU.
Mayan wins: Fine-grained permissions and workflow controls for regulated teams.

Paperless-ngx vs Docspell (Docspell Alternative)

Stack: Python/Django with broad integrations; Docspell is Scala with a smaller ecosystem.
Automation: Docspell has native routing rules; Paperless-ngx leaves complex pipelines to your scripts.
Docspell wins: Email and folder automation without custom cron or n8n glue.

Paperless-ngx vs Papermerge (Papermerge Alternative)

Model: Tags and correspondents map cleanly to API fields; Papermerge is folder-first.
Bulk intake: One post_document call sets file, title, and tags; Papermerge's API is less metadata-rich.
Papermerge wins: A simpler folder hierarchy if you do not want tagging logic.

Paperless-ngx vs Google Drive (Google Drive Alternative)

Privacy: OCR text and files stay on your server; Drive keeps them on Google infrastructure.
API friction: No OAuth scopes or per-call quotas; Drive adds auth overhead for scripts.
Drive wins: Zero setup, collaborative editing, and built-in backups; you own all that with Paperless-ngx.

How to use Paperless-ngx API (the OSS document management system)?

Log in with the admin user and password from Railway variables, then open My Profile and create an API token. Keep it secret.

Test the API:

curl -H "Authorization: Token YOUR-TOKEN" https://your-domain/api/documents/

Get tag and correspondent ids from /api/tags/ and /api/correspondents/; the API takes ids, not names.

Upload a file with optional metadata:

curl -F "document=@invoice.pdf" -F "title=Invoice" -F "tags=3" \
  -H "Authorization: Token YOUR-TOKEN" \
  https://your-domain/api/documents/post_document/

The upload returns a task UUID, not a document id, because OCR runs async. Poll it:

curl -H "Authorization: Token YOUR-TOKEN" \
  "https://your-domain/api/tasks/?task_id=UUID"

When the task shows a document id, you're done. Wire the same curl into n8n or a cron job.

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

Clone the Repository

On a VPS, get the official compose file. You don't need the full source tree, just the deployment bits.

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

Install Dependencies

Install Docker and Docker Compose. The compose stack pulls Postgres and Redis automatically, so no separate database setup is required.

Configure Environment Variables

Copy the example env file and set your values. You'll need a secret key, your public URL, and database credentials.

cp docker/compose/docker-compose.env .env
nano .env

Set PAPERLESS_SECRET_KEY, PAPERLESS_URL=https://your-domain, PAPERLESS_ADMIN_USER, PAPERLESS_ADMIN_PASSWORD, and the Postgres variables.

Start the Paperless-ngx API Application

Launch the stack and wait for the web container to come up.

docker compose up -d

Then open your-domain, log in with the admin account, and create an API token in My Profile. Railway handles all of this orchestration for you.

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

Paperless-ngx is fully free and open source under GPL-3.0. There is no license fee, no paid tier, no per-document charge, and no official cloud from the project. You only pay for infrastructure: the Railway container, Postgres, Redis, and volume storage. Third-party hosts exist, but their prices are not set by Paperless-ngx.

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

Paperless-ngx has no official paid cloud, so self hosting is the normal path. The API itself adds no license cost; your real expenses are compute, storage, and backups.

Monthly cost of self hosting Paperless-ngx API on Railway

Plan for about $5-15/mo for a small personal archive on Railway. Volume storage grows with your documents, so bulk OCR or years of PDFs push that higher. The Railway $5 trial is enough to test token-based uploads before committing.

System Requirements for Hosting Paperless-ngx API on a VPS

Docker Compose is the officially recommended route. The stack runs on a Raspberry Pi, but OCR gets slow on weak CPUs. Disk sizing depends on media and archive copies, not just raw PDFs.

Frequently Asked Questions (FAQs)

Where do I get an API token?

In the web UI, go to My Profile, then API Auth Token. Copy the token and send it as the header Authorization: Token your-token.

Why does upload return a UUID instead of a document id?

Uploads return a task UUID because OCR and matching run in the background. Poll GET /api/tasks/?task_id=the-uuid to get the new document id when done.

Can I set tags by name?

No, only numeric ids. Look them up at /api/tags/ and /api/correspondents/ first, then repeat the tags field per id.

Is there a rate limit on the API?

No documented per-user rate limit, but this is your server. Keep bursts modest and retry on HTTP 429 or 503.

Can n8n use this API?

Yes. Use HTTP Request nodes with the Authorization header and multipart form data, then poll the task endpoint for the document id.

Does the API bypass consumption folder rules?

No, API uploads go through the same consumer as the consumption folder and email, so matching rules, tags, and workflows still apply.