Paperless-ngx is an open-source document management system that takes PDFs, scans and office documents, extracts searchable text, and organises them with correspondents, document types, tags and custom fields. You keep the files and database on infrastructure you control instead of sending financial records, contracts or household paperwork to another subscription service.
The installation is only the beginning. A useful Paperless server also needs a stable database, correct OCR languages, encrypted access, a sensible import workflow and a backup containing both the documents and their metadata. This guide builds that complete path on an Ubuntu VPS.
Why Run Paperless-ngx on a VPS?
| Benefit | What it means in practice |
|---|---|
| Private ownership | Original documents, OCR text and metadata remain on your server. |
| Access anywhere | Use a secured HTTPS address rather than leaving the archive on one home computer. |
| Searchable scans | OCR turns image-only paperwork into text you can search. |
| Automated filing | Rules can assign tags, correspondents and document types during consumption. |
| Repeatable deployment | Docker Compose keeps the application, database and task queue clearly defined. |
Self-hosting does not remove responsibility. Anyone with access may be able to read sensitive documents, so use strong credentials, HTTPS, restricted administration and tested backups from day one.
Choose the Right VPS
For a personal archive, begin with 2 vCPU, 4 GB RAM and 40 GB of SSD storage. Increase to 4 vCPU and 8 GB RAM when importing large batches, enabling several OCR languages or serving multiple users. Storage use depends far more on the documents than the application itself.
- Ubuntu 24.04 or 26.04 with full root access
- 2 vCPU and 4 GB RAM as a practical starting point
- Enough storage for originals, archive copies, thumbnails and database backups
- One public IPv4 address and a DNS name
- TCP 80 and 443 available for the reverse proxy
Paperless creates an archival version alongside some originals, so do not size the disk to the current folder alone. Leave room for growth, exports and local backup staging. For a large archive, place the application and PostgreSQL working data on SSD and the media library on suitable capacity storage.
Prepare Ubuntu and Docker
Patch the server first, create a dedicated directory and install Docker Engine with the Compose plugin. Our Docker on Ubuntu guide covers the official repository process in detail.
sudo apt update
sudo apt full-upgrade -y
sudo mkdir -p /opt/paperless
sudo chown "$USER":"$USER" /opt/paperless
cd /opt/paperless
docker --version
docker compose versionKeep SSH limited to trusted addresses, enable automatic security updates and do not expose PostgreSQL or Redis publicly. Only the reverse proxy should accept public web traffic.
Install Paperless-ngx with Docker Compose
The Paperless-ngx project publishes supported Compose examples. Download its current PostgreSQL configuration rather than copying an old version from an abandoned tutorial:
cd /opt/paperless
curl -LO https://raw.githubusercontent.com/paperless-ngx/paperless-ngx/main/docker/compose/docker-compose.postgres.yml
curl -LO https://raw.githubusercontent.com/paperless-ngx/paperless-ngx/main/docker/compose/docker-compose.env
curl -Lo .env https://raw.githubusercontent.com/paperless-ngx/paperless-ngx/main/docker/compose/.env
mv docker-compose.postgres.yml docker-compose.ymlOpen docker-compose.env and set the public URL, timezone, OCR language and a long secret key:
PAPERLESS_URL=https://docs.example.com
PAPERLESS_TIME_ZONE=Europe/London
PAPERLESS_OCR_LANGUAGE=eng
PAPERLESS_SECRET_KEY=replace-with-a-long-random-value
PAPERLESS_ADMIN_USER=admin
PAPERLESS_ADMIN_PASSWORD=replace-with-a-unique-password
PAPERLESS_ADMIN_MAIL=admin@example.comGenerate the secret locally with openssl rand -base64 48. Do not reuse your panel, email or SSH password. Confirm the volume paths in Compose, then pull and start the stack:
docker compose pull
docker compose up -d
docker compose ps
docker compose logs --tail=100 webserverThe default stack includes the Paperless webserver, task consumer, Redis and PostgreSQL. Wait for migrations to finish before opening the interface.
Configure OCR, Users and Filing Rules
English OCR uses eng. Add additional language packages through the project-supported environment variables when your archive contains other languages. More OCR languages increase processing time and can reduce accuracy when enabled indiscriminately, so select only those you use.
After signing in, create ordinary accounts for daily use and reserve the administrator account for configuration. Then build a small vocabulary before importing everything:
- Correspondents: bank, insurer, supplier or public authority
- Document types: invoice, statement, contract, receipt or letter
- Tags: tax year, property, project, person or retention status
- Custom fields: renewal date, account number or monetary amount
Start with a few documents and tune matching rules. A modest filing system you understand beats hundreds of overlapping tags generated on day one.
Put Paperless-ngx Behind HTTPS
Create an A record for the chosen hostname, then use Caddy, Nginx Proxy Manager or Traefik as the public endpoint. Keep Paperless bound to localhost when the proxy runs on the host:
ports:
- "127.0.0.1:8000:8000"A minimal Caddy site is:
docs.example.com {
reverse_proxy 127.0.0.1:8000
encode zstd gzip
}Set PAPERLESS_URL to the same HTTPS address. Do not publish port 8000 directly to the internet after the proxy works. Consider VPN-only access for especially sensitive personal or business archives.
Build a Reliable Import Workflow
Upload through the browser
This is the simplest option for occasional files and gives immediate control over metadata.
Use the consume directory
Files copied into the consume volume are picked up automatically. A network scanner can deliver to a secured share that feeds this directory, but do not expose an unauthenticated SMB share publicly.
Import from email
Paperless can monitor a mailbox and process matching attachments. Use a dedicated mailbox or folder, restrict its credentials and write rules that reject unexpected senders or file types.
Keep the original paper until you have verified the scan, OCR, page count and backup. Paperless helps organise records; it does not decide which physical documents you are legally required to retain.
Back Up Documents and Metadata Together
A complete Paperless backup needs the media files and the PostgreSQL database from the same point in time. Backing up only PDFs loses tags, correspondents, users and workflow state; backing up only PostgreSQL loses the documents.
cd /opt/paperless
mkdir -p export
docker compose exec -T webserver document_exporter ../export
tar -czf "paperless-export-$(date +%F).tar.gz" exportThe project exporter creates a portable package designed for restoration. Copy it to a different server or storage provider, encrypt sensitive archives at rest, and rotate old backups. Test document_importer in a separate temporary deployment at least once; an untested archive is only a hopeful copy.
Update Without Gambling with the Archive
Read the Paperless-ngx release notes before moving between versions. Create an export and a VPS snapshot, then pull and recreate containers:
cd /opt/paperless
docker compose pull
docker compose up -d
docker compose ps
docker compose logs --tail=100 webserverDo not automatically track unreviewed major releases on a document system. Keep the Compose and environment files in a private configuration repository with secrets excluded, and record the last known-good image versions.
Common Paperless-ngx Problems
| Symptom | Likely cause | Check |
|---|---|---|
| Document stays pending | Consumer stopped or Redis unavailable | docker compose ps and consumer logs |
| OCR language error | Language package is not installed | Configured OCR languages and image variant |
| Bad CSRF or origin error | Public URL does not match the proxy hostname | PAPERLESS_URL and proxy headers |
| Uploads fail | Volume permissions or full disk | df -h, UID/GID and bind-mount ownership |
| Search misses scans | Poor source quality or incorrect OCR language | Scan resolution, contrast and OCR configuration |
| Importer duplicates files | Same document entered through multiple paths | Mail rules, consume folder and duplicate handling |
Paperless-ngx VPS FAQ
How much RAM does Paperless-ngx need?
A personal archive can start with 2 vCPU and 4 GB RAM. Large OCR batches and multiple users benefit from 4 vCPU and 8 GB RAM or more.
Does it need PostgreSQL and Redis?
Redis handles background tasks. PostgreSQL is the recommended database for a durable server deployment and is preferable to SQLite as the archive grows.
Where are the documents stored?
Originals and archival copies are stored in the media volume. Metadata and search state live in PostgreSQL, so a complete backup includes both.
Can it import documents from email?
Yes. Paperless can monitor mailboxes and process attachments using rules. A dedicated mailbox or folder keeps the permissions and workflow easier to audit.
Can I use a Storage VPS?
Yes, particularly when archive capacity matters more than SSD latency. Keep application and database working data on the included SSD boot disk where practical and place the media archive on HDD storage.
Is Paperless-ngx a backup?
No. It is the live document system. Maintain separate encrypted exports or snapshots in another failure domain and test restoration.
Make the Archive Boringly Dependable
The useful version of a paperless office is not merely a container that starts. It is an archive with predictable imports, accurate OCR, controlled access, enough storage, documented updates and a restore procedure someone has actually tested.
Deploy Paperless-ngx on a HYEHOST Cloud VPS for responsive everyday use, or pair its media library with a Storage VPS when long-term capacity becomes the larger concern.