Self-host Paperless-ngx

Arct Cloud provides the unmanaged Linux VPS for this deployment. Paperless-ngx is not preinstalled or managed by Arct Cloud, and you are responsible for the application, document privacy, backups, security, and updates.

Paperless-ngx stores potentially sensitive documents. Keep its application port private, require HTTPS, use strong account credentials, and maintain encrypted off-server backups.

Choose a Plan

Paperless-ngx does not publish a single minimum VPS size. OCR speed and memory use vary with document length, image resolution, language packs, concurrent workers, and optional services.

Arct plan	vCPU	RAM	NVMe storage	Suggested use
cvm.micro	2	4 GB	40 GB	Personal archive and light OCR volume
cvm.small	4	8 GB	75 GB	Larger imports, multiple users, or faster OCR processing

These are Arct recommendations rather than upstream requirements. Review current resources on the Arct Cloud pricing page and leave capacity for originals, archived PDFs, thumbnails, the database, Redis, and exports.

Before You Begin

Prepare the following:

A fresh Ubuntu 24.04 server
A domain or subdomain such as documents.example.com
An A record pointing that hostname to the server’s public IPv4 address
Docker Engine with the Docker Compose plugin, installed from the official Docker repository
A reverse proxy such as Caddy or Nginx

Paperless-ngx supports several installation routes. This guide uses the project’s official PostgreSQL Compose template and manual Compose flow so the port, database password, and application secret can be secured before any container starts.

Install Paperless-ngx

Deploy and Connect

Deploy an Ubuntu server, then connect over SSH.

Allow the Ubuntu User to Run Docker

After installing Docker Engine and the Compose plugin from Docker’s official Ubuntu repository, add the default Ubuntu user to the Docker group:

sudo usermod -aG docker ubuntu
exit

Reconnect so the group membership takes effect, then verify Docker and Compose work without sudo:

ssh ubuntu@YOUR_SERVER_IP
docker version
docker compose version

The docker group grants effective root access through privileged containers and host mounts. Add only trusted administrator accounts.

Download the Official Compose Templates

Create the application directory and download the three files from Paperless-ngx’s official PostgreSQL Compose example:

sudo install -d -m 0750 -o "$USER" -g "$USER" /opt/paperless
cd /opt/paperless

curl -fsSLo docker-compose.yml \
  https://raw.githubusercontent.com/paperless-ngx/paperless-ngx/main/docker/compose/docker-compose.postgres.yml
curl -fsSLo docker-compose.env \
  https://raw.githubusercontent.com/paperless-ngx/paperless-ngx/main/docker/compose/docker-compose.env
curl -fsSLo .env \
  https://raw.githubusercontent.com/paperless-ngx/paperless-ngx/main/docker/compose/.env

Review these files and compare their URLs with the current official setup documentation before continuing.

Secure the Template Before First Start

Patch the official template while it is still offline. This binds Paperless to loopback, replaces the template PostgreSQL password, and passes the same password to the webserver:

cd /opt/paperless
sed -i 's|      - "8000:8000"|      - "127.0.0.1:8000:8000"|' \
  docker-compose.yml
sed -i 's|      POSTGRES_PASSWORD: paperless|      POSTGRES_PASSWORD: ${PAPERLESS_DB_PASSWORD:?set PAPERLESS_DB_PASSWORD in .env}|' \
  docker-compose.yml
sed -i '/      PAPERLESS_DBENGINE: postgresql/a\      PAPERLESS_DBPASS: ${PAPERLESS_DB_PASSWORD:?set PAPERLESS_DB_PASSWORD in .env}' \
  docker-compose.yml

Generate separate database and application secrets, configure the public URL, and lock both environment files to the current user:

umask 077
database_password="$(openssl rand -hex 32)"
application_secret="$(openssl rand -hex 48)"

printf '\nPAPERLESS_DB_PASSWORD=%s\n' "$database_password" >>.env
sed -i "s/^PAPERLESS_SECRET_KEY=.*/PAPERLESS_SECRET_KEY=${application_secret}/" \
  docker-compose.env
sed -i 's|^#PAPERLESS_URL=.*|PAPERLESS_URL=https://documents.example.com|' \
  docker-compose.env
unset database_password application_secret

chmod 0600 .env docker-compose.env
install -d -m 0700 export
install -d -m 0750 consume

Validate the security-critical changes before pulling or starting anything:

grep -F '127.0.0.1:8000:8000' docker-compose.yml
grep -F 'PAPERLESS_DB_PASSWORD' docker-compose.yml
test "$(stat -c '%a' docker-compose.env)" = 600
test "$(stat -c '%a' .env)" = 600
test "$(stat -c '%a' export)" = 700

if grep -Eq '^[[:space:]]*-[[:space:]]*"8000:8000"' docker-compose.yml; then
  echo 'Refusing to start: Paperless would bind to every interface.' >&2
  exit 1
fi

docker compose config --quiet

Do not run docker compose up unless every validation above succeeds. The upstream template’s unmodified 8000:8000 mapping publishes the first-login screen on every network interface.

Start the Private Stack and Create the Superuser

Only after the loopback and secret checks pass, start the stack and create the initial superuser from the server terminal:

cd /opt/paperless
docker compose pull
docker compose up -d
docker compose ps
docker compose run --rm webserver createsuperuser

From a second terminal on your local computer, tunnel to the loopback-only service:

ssh -N -L 8000:127.0.0.1:8000 ubuntu@YOUR_SERVER_IP

Open http://127.0.0.1:8000, sign in with the superuser, and verify the private installation. Stop the tunnel with Ctrl+C after the check.

Enable HTTPS

Install Caddy using its official Debian and Ubuntu instructions, then add this block to /etc/caddy/Caddyfile:

documents.example.com {
    reverse_proxy 127.0.0.1:8000
}

sudo caddy validate --config /etc/caddy/Caddyfile
sudo systemctl reload caddy

Verify and Harden the Account

Open https://documents.example.com and sign in with the superuser created privately. Create a non-superuser account for routine document work, restrict user permissions, and keep the superuser for administration only.

docker compose ps
docker compose logs --tail=100 webserver

Firewall and OCR Controls

Allow SSH before enabling UFW:

sudo ufw allow OpenSSH
sudo ufw allow 80/tcp
sudo ufw allow 443/tcp
sudo ufw enable
sudo ufw status

Do not expose Paperless port 8000, PostgreSQL, or Redis publicly. For limited servers, reduce concurrent workers, avoid unnecessary OCR language packs, keep PAPERLESS_OCR_MODE at its default, and consider limiting OCR pages or image-cleaning work according to the upstream low-resource guidance.

Back Up and Restore

Pause new document consumption before exporting. The official exporter includes documents, thumbnails, metadata, settings, and database content in the Compose export directory. Keep that directory mode 0700 and require it to be empty so old plaintext exports are not mixed into a new recovery set:

cd /opt/paperless
chmod 0700 export
test -z "$(find export -mindepth 1 -maxdepth 1 -print -quit)" || {
  echo 'Move or remove the previous plaintext export before continuing.' >&2
  exit 1
}
docker compose exec -T webserver document_exporter ../export

Encrypt the export and deployment configuration before it leaves the VPS. The example below uses an age recipient public key; keep the matching private identity off the Paperless server:

sudo apt update
sudo apt install -y age

(
  set -euo pipefail
  cd /opt/paperless
  stamp="$(date -u +%Y%m%dT%H%M%SZ)"
  plaintext="/tmp/paperless-${stamp}.tar.gz"
  encrypted="${plaintext}.age"
  metadata="/tmp/paperless-${stamp}-image.txt"

  docker inspect "$(docker compose ps -q webserver)" \
    --format '{{.Config.Image}} {{.Image}}' >"$metadata"
  tar -czf "$plaintext" \
    export docker-compose.yml docker-compose.env .env \
    -C /tmp "$(basename "$metadata")"
  age -r 'age1REPLACE_WITH_YOUR_BACKUP_RECIPIENT' \
    -o "$encrypted" "$plaintext"
  sha256sum "$encrypted"
  printf 'Encrypted backup ready: %s\n' "$encrypted"
)

Copy only the .age file to off-server storage and compare its SHA-256 hash at the destination. After the remote copy is verified, remove the short-lived local plaintext, local encrypted staging file, metadata file, and exporter output:

rm -f -- /tmp/paperless-*.tar.gz /tmp/paperless-*.tar.gz.age \
  /tmp/paperless-*-image.txt
find /opt/paperless/export -mindepth 1 -delete

Unlinking files cannot guarantee physical erasure on SSD storage, so use encrypted storage and keep plaintext retention as short as possible. API tokens are not included and must be created again after a restore. Exports are version-specific; the encrypted archive includes the exact webserver image metadata and the protected Compose environment files used for that backup. Restore with the official document_importer into an empty installation running a compatible version. Review the backup and restore documentation and test the full procedure before relying on it.

Update Safely

Read the release notes and any referenced migration guide. Stop consumption, create an off-server export, then update the Compose deployment:

docker compose down
docker compose pull
docker compose up -d
docker compose ps
docker compose logs --tail=150 webserver

Container startup applies database migrations. Do not interrupt migrations or attempt a downgrade against a migrated database; restore a compatible pre-update backup instead.

Troubleshooting

Symptom	Check
OCR jobs are slow or the server swaps	Reduce worker concurrency and optional OCR processing, then monitor CPU, RAM, and free disk.
Files remain in the consume directory	Check consumer logs, directory ownership, `USERMAP_UID`/`USERMAP_GID`, and whether the filesystem supports inotify.
Login redirects to HTTP or the wrong host	Confirm `PAPERLESS_URL` matches the public HTTPS URL and reload the containers.
Caddy returns `502`	Confirm the webserver is healthy and bound to `127.0.0.1:8000`.
An update fails	Stop, inspect webserver/database logs and release notes, and restore the matching backup rather than repeatedly restarting migrations.

Official Resources

Paperless-ngx Setup

Official installation routes, Compose templates, and low-resource guidance.

Paperless-ngx on GitHub

Source code, releases, issues, and security policy.

Paperless-ngx is developed independently of Arct Cloud. Arct Cloud is an independent infrastructure provider and is not affiliated with, sponsored by, or endorsed by the Paperless-ngx project.

Getting Started

Virtual Machines

Migrations

Billing & Payments

Account

Self-host Paperless-ngx

Choose a Plan

Before You Begin

Install Paperless-ngx

Firewall and OCR Controls

Back Up and Restore

Update Safely

Troubleshooting

Official Resources

Paperless-ngx Setup

Paperless-ngx on GitHub

​Choose a Plan

​Before You Begin

​Install Paperless-ngx

​Firewall and OCR Controls

​Back Up and Restore

​Update Safely

​Troubleshooting

​Official Resources

Paperless-ngx Setup

Paperless-ngx on GitHub

Choose a Plan

Before You Begin

Install Paperless-ngx

Firewall and OCR Controls

Back Up and Restore

Update Safely

Troubleshooting

Official Resources