---
title: "Deploy paperless-ngx"
description: "Document management with OCR on Railway with PostgreSQL and Redis"
category: "Starters"
url: https://railway.com/deploy/paperless-ngx-3
---

# Deploy paperless-ngx

Document management with OCR on Railway with PostgreSQL and Redis

**[Deploy paperless-ngx on Railway](https://railway.com/template/paperless-ngx-3)**

- **Creator:** INAPP
- **Category:** Starters

## Template content

### Redis https://cdn.sanity.io/images/sy1jschh/production/0ce0bfdcfbdbf69662b1116671f97c2dd788b655-157x157.svg

- **Image:** redis:8.2.1
- **Start command:** `/bin/sh -c "rm -rf $RAILWAY_VOLUME_MOUNT_PATH/lost+found/ && exec docker-entrypoint.sh redis-server --requirepass $REDIS_PASSWORD --save 60 1 --dir $RAILWAY_VOLUME_MOUNT_PATH"`

### Postgres https://devicons.railway.app/i/postgresql.svg

- **Image:** ghcr.io/railwayapp-templates/postgres-ssl:18

### paperless-ngx

- **Source:** https://github.com/INAPP-Mobile/paperless-ngx-railway
- **Public domain:** Yes

## Documentation

[![Deploy to Railway](https://railway.app/button.svg)](https://railway.com/deploy/paperless-ngx-3)

# Deploy and Host Paperless-ngx on Railway

Paperless-ngx is the fork of the original Paperless application — a document management system that transforms your physical documents into a searchable digital archive. It features OCR, automatic tagging, document classification, and a modern web interface.

## About Hosting Paperless-ngx on Railway

This template deploys Paperless-ngx with PostgreSQL (database), Valkey/Redis (task broker), and persistent storage volumes on Railway. The Paperless service runs the web server and background task consumer in a single process.

### Features

- **OCR & Text Extraction** — Automatic text recognition from scanned documents
- **Document Tagging** — Automatic and manual tagging with AI-powered suggestions
- **Search** — Full-text search across all documents
- **Document Types** — Support for PDF, Office docs, images, emails, and more
- **Consumption Directory** — Drop files to automatically ingest and process
- **API** — RESTful API for programmatic access
- **Multi-user** — Role-based access control with Django auth
- **Dark Mode** — Built-in dark theme support

## Why Deploy Paperless-ngx on Railway

- **One-click deployment** — PostgreSQL and Redis are set up automatically as companion services
- **Persistent storage** — Database and document data persist across deploys via Railway volumes
- **Auto-scaling** — Scale vertically as your document archive grows
- **Custom domains** — Add your own domain with automatic TLS certificates
- **Managed infrastructure** — No need to manage your own database or Redis instances

## Quick Start

1. Click the Deploy to Railway button above
2. Wait for provisioning (~2-3 minutes for image pull and DB init)
3. Open the application at your deployed Railway URL
4. The default admin credentials are printed in the deployment logs

## Prerequisites

- A Railway account (free tier available)
- No local setup required — everything runs on Railway

## Architecture

```
                    ┌─────────────────────────────────────────────────────┐
                    │           Railway Project                           │
                    │                                                     │
  ┌─────────────┐   │  ┌──────────────────────┐                         │
  │  PostgreSQL │   │  │   Paperless-ngx      │                         │
  │  (companion)│   │  │   (main service)     │                         │
  │  port 5432  │   │  │   port 8000          │                         │
  └─────────────┘   │  └──────────┬───────────┘                         │
                    │             │                                      │
  ┌─────────────┐   │             │                                      │
  │  Valkey     │   │             │                                      │
  │  (Redis)    │   │             │                                      │
  │  (companion)│   │             │                                      │
  │  port 6379  │   │             │                                      │
  └─────────────┘   │             │                                      │
                    │             │                                      │
                    │  ┌──────────▼───────────┐                          │
                    │  │  Persistent Volumes  │                          │
                    │  │  (postgres + redis   │                          │
                    │  │   + paperless data)  │                          │
                    │  └──────────────────────┘                          │
                    └─────────────────────────────────────────────────────┘
```

## Common Use Cases

- Personal document archiving and search
- Small office paperless workflow
- Receipt and invoice management
- Academic paper organization
- Legal document management

## Dependencies for Paperless-ngx on Railway

This template requires the following services:

### Deployment Dependencies

- **PostgreSQL** — Required. Automatically deployed as a companion service.
- **Valkey/Redis** — Required. Automatically deployed as a companion service for Celery task broker.

## Configuration

### Environment Variables

| Variable | Default | Description |
|----------|---------|-------------|
| `PORT` | `8000` | Port for the Paperless-ngx web server |
| `PAPERLESS_SECRET_KEY` | (auto) | Secret key for session tokens and signing. Auto-generated if not set. |
| `PAPERLESS_REDIS` | (auto) | Redis connection string. Auto-detected from the Redis companion service. |
| `PAPERLESS_DBENGINE` | `postgresql` | Database engine (postgresql) |
| `PAPERLESS_DBHOST` | (auto) | PostgreSQL host. Auto-detected from the Postgres companion service. |
| `PAPERLESS_DBPORT` | `5432` | PostgreSQL port |
| `PAPERLESS_DBNAME` | `paperless` | Database name. Must match `POSTGRES_DB` on the Postgres service. |
| `PAPERLESS_DBUSER` | (auto) | PostgreSQL username. Auto-detected from the Postgres companion service. |
| `PAPERLESS_DBPASS` | (auto) | PostgreSQL password. Auto-detected from the Postgres companion service. |
|| `PAPERLESS_DB_OPTIONS` | `{"sslmode": "prefer"}` | PostgreSQL connection options (JSON) |\
|| `PAPERLESS_URL` | (auto) | Public URL. Auto-detected from the Railway domain. |
| `PAPERLESS_TIME_ZONE` | `UTC` | Timezone for document processing |
| `PAPERLESS_OCR_LANGUAGE` | `eng` | Default OCR language |
| `PAPERLESS_OCR_LANGUAGES` | `eng` | Additional OCR languages (space-separated) |
| `PAPERLESS_CONSUMER_RECURSIVE` | `true` | Whether consumer recursively scans subdirectories |
| `PAPERLESS_CONSUMER_POLLING_INTERVAL` | `0` | Polling interval (0 = event-driven) |

### Postgres Service

| Variable | Default | Description |
|----------|---------|-------------|
| `POSTGRES_USER` | `paperless` | Database superuser |
| `POSTGRES_PASSWORD` | auto-generated | Database password (auto-generated secret) |
| `POSTGRES_DB` | `paperless` | Initial database name |
| `PGDATA` | `/var/lib/postgresql/data/pgdata` | Postgres data directory |

### Redis Service

| Variable | Default | Description |
|----------|---------|-------------|
| `REDIS_PASSWORD` | auto-generated | Redis password (auto-generated secret) |
| `REDIS_URL` | `redis://:${REDIS_PASSWORD}@${RAILWAY_PRIVATE_DOMAIN}:6379` | Redis/Valkey connection URL with password |

## Persistent Storage

Each service has a Railway volume attached for data persistence:

- **PostgreSQL** — `postgres-volume` mounted at `/var/lib/postgresql/data`
- **Redis** — `redis-volume` mounted at `/data`
- **Paperless-ngx** — `paperless-ngx-volume` mounted at `/usr/src/paperless/data` (consumption directory, OCR cache, and other state)

Note: Railway limits each service to one volume. The Paperless-ngx media directory (`/usr/src/paperless/media`) is not persisted on a separate volume — generated thumbnails and media files can be regenerated by the application.

The Paperless-ngx service exposes a health endpoint at `/health`. Railway monitors this endpoint to ensure the service is running. The endpoint returns a 302 redirect to the login page when unauthenticated, which Railway accepts as a healthy response.

## Project Structure

```
├── Dockerfile              # Paperless-ngx service build (uses official image)
├── docker-entrypoint.sh    # Railway-aware entrypoint (auto-configures DB/Redis/URL)
├── railway.json            # Railway build/deploy config
├── postgres/
│   ├── Dockerfile          # Postgres service build
│   ├── railway.json        # Postgres deploy config with volume mount
│   └── template-vars.json  # Postgres template variables
├── redis/
│   ├── Dockerfile          # Valkey/Redis service build
│   ├── railway.json        # Redis deploy config with volume mount
│   └── template-vars.json  # Redis template variables
├── template-vars.json      # Template variables for Railway marketplace
└── template-editor-raw.json # Raw template editor variable values
```

## Security Notes

- Change the default Postgres password (`paperless`) after first deployment
- Set a strong `PAPERLESS_SECRET_KEY` for session token signing (auto-generated on first deploy if left as default)
- Configure a custom domain with HTTPS for production use
- The default admin credentials are printed in the Railway deployment logs after first startup

## Learn More

- [Paperless-ngx Documentation](https://docs.paperless-ngx.com)
- [Paperless-ngx GitHub](https://github.com/paperless-ngx/paperless-ngx)
- [Railway Documentation](https://docs.railway.app)


## Similar templates

- [open-excalidraw](https://railway.com/deploy/open-excalidraw) — Self-hostable collaborative drawing built on Excalidraw
- [caring-vibrancy](https://railway.com/deploy/caring-vibrancy) — Deploy and Host caring-vibrancy with Railway
- [Appsmith](https://railway.com/deploy/appsmith-1) — Low-code platform for internal tools, dashboards, and admin panels.

Open this page in a browser: https://railway.com/deploy/paperless-ngx-3