Setting Up Paperless-ngx: Go Paperless on Your Linux Server

Paperless-ngx is an open source document management system that lets you scan, tag, search, and archive all your documents — bills, contracts, receipts, letters — on your own server. With OCR built in, every document becomes fully searchable. This guide walks through a complete Docker-based installation on Ubuntu.

Prerequisites

Ubuntu 22.04 server (or any Linux distro with Docker support)
At least 2 GB RAM (4 GB recommended for OCR processing)
Docker and Docker Compose installed
Basic familiarity with the command line

Step 1: Install Docker and Docker Compose

If Docker is not already installed, add the official Docker repository and install it:

sudo apt update
sudo apt install -y ca-certificates curl gnupg
sudo install -m 0755 -d /etc/apt/keyrings
curl -fsSL https://download.docker.com/linux/ubuntu/gpg | \
  sudo gpg --dearmor -o /etc/apt/keyrings/docker.gpg
echo "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.gpg] \
  https://download.docker.com/linux/ubuntu $(lsb_release -cs) stable" | \
  sudo tee /etc/apt/sources.list.d/docker.list > /dev/null
sudo apt update
sudo apt install -y docker-ce docker-ce-cli containerd.io docker-compose-plugin

Add your user to the Docker group so you don't need sudo for every command:

sudo usermod -aG docker $USER
newgrp docker

Step 2: Create the Paperless-ngx Directory

Create a dedicated folder for Paperless-ngx and its data:

mkdir -p ~/paperless-ngx
cd ~/paperless-ngx

Step 3: Download the Docker Compose File

Paperless-ngx provides an official Docker Compose configuration. Download it along with the environment file:

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

Step 4: Configure the Environment File

Open .env and set the following values:

nano .env

Key settings to update:

# Set a strong random secret key (generate one with: openssl rand -hex 32)
PAPERLESS_SECRET_KEY=your_long_random_secret_key_here

# Your server's IP or domain name
PAPERLESS_URL=http://your-server-ip:8000

# Default language for OCR (use your document language)
PAPERLESS_OCR_LANGUAGE=eng

# Timezone
PAPERLESS_TIME_ZONE=Europe/London

# Database password
POSTGRES_PASSWORD=StrongDBPassword123!

Step 5: Start Paperless-ngx

Pull the images and start all containers in the background:

docker compose pull
docker compose up -d

The first start takes a few minutes as it initialises the database and downloads language packs for OCR. Check the logs to monitor progress:

docker compose logs -f webserver

Once you see Listening at: http://0.0.0.0:8000, the application is ready.

Step 6: Create Your Admin Account

Create the initial superuser account to log in:

docker compose exec webserver python3 manage.py createsuperuser

Enter a username, email address, and strong password when prompted.

Step 7: Log In and Explore

Open a browser and navigate to http://your-server-ip:8000. Log in with the account you just created. You'll land on the dashboard — empty for now, but ready for documents.

Step 8: Add Your First Document

The easiest way to add documents is via the web upload. Click the upload button in the top right, drag and drop a PDF or image file, and Paperless-ngx will:

Run OCR to make it fully searchable
Generate a thumbnail preview
Store it in its database with metadata

For automated ingestion, drop files into the consumption folder on the server:

# Find the consumption folder path
docker compose exec webserver printenv PAPERLESS_CONSUMPTION_DIR

Any file placed in that folder is automatically processed and imported — perfect for pairing with a network scanner.

Step 9: Set Up Tags and Correspondents

Paperless-ngx shines when you use its organisation features:

Tags — label documents by category (Invoices, Medical, Bank, Tax)
Correspondents — track who sent each document (HMRC, your bank, a utility company)
Document types — classify by type (Invoice, Statement, Letter, Contract)
Workflows — automatically assign tags and correspondents based on content matching rules

Go to Settings → Workflows and create a rule like: if the document contains "electricity bill", assign tag "Utilities" and correspondent "British Gas" automatically.

Step 10: Keep It Updated

Pulling the latest Paperless-ngx image is straightforward:

cd ~/paperless-ngx
docker compose pull
docker compose up -d

Paperless-ngx handles database migrations automatically on startup.

What's Next?

Put it behind Nginx — set up a reverse proxy so you can access it at a domain like docs.yourdomain.com with HTTPS via Let's Encrypt
Mobile access — the web interface is fully responsive; bookmark it on your phone for quick document access anywhere
Automated backups — add a cron job to back up the PostgreSQL database and the media folder to an external location
Scanner integration — pair with a network scanner to auto-drop scanned documents into the consumption folder for a fully paperless workflow

The Paperless-ngx documentation covers advanced topics including custom storage paths, remote user authentication, and the REST API.