How to Self-Host Paperless-ngx and Access Your Documents from Anywhere

What Is Paperless-ngx?

Paperless-ngx is an open-source document management system. You feed it documents, either by dropping files into a folder, uploading through its web interface, emailing them to a configured inbox, or using a mobile app, and it does the following automatically:

What Gets Installed: The Four Containers

Paperless-ngx uses a multi-container setup. Understanding what each container does makes troubleshooting and configuration much easier.

The minimal setup (webserver + broker + db) handles PDFs and images. Adding Gotenberg and Tika enables Office documents and emails. This guide uses the full stack.

Prerequisites

You need a Linux server with Docker and Docker Compose installed. This guide uses Ubuntu 22.04 or 24.04, but the same steps work on Debian, Raspberry Pi OS, and any other Debian-based distribution. Paperless-ngx supports amd64, arm, and arm64 hardware.

Step 1: Create the Directory and Download the Compose Files

Create a directory for Paperless-ngx and navigate into it. All your data, configuration, and document volumes will live here.

mkdir ~/paperless-ngx
cd ~/paperless-ngx
mkdir consume export

The consume directory is where you drop documents to be imported. The export directory is used for backups. Create both before starting the containers or Docker will create them as root-owned directories, which causes permission errors.

Now create the main docker-compose.yml file. This is based directly on the official docker-compose.postgres-tika.yml from the Paperless-ngx GitHub repository, which is the full-featured stack:

services:
  broker:
    image: docker.io/library/redis:8
    restart: unless-stopped
    volumes:
      - redisdata:/data

  db:
    image: docker.io/library/postgres:18
    restart: unless-stopped
    volumes:
      - pgdata:/var/lib/postgresql/data
    environment:
      POSTGRES_DB: paperless
      POSTGRES_USER: paperless
      POSTGRES_PASSWORD: paperless

  webserver:
    image: ghcr.io/paperless-ngx/paperless-ngx:latest
    restart: unless-stopped
    depends_on:
      - db
      - broker
      - gotenberg
      - tika
    ports:
      - "127.0.0.1:8000:8000"
    volumes:
      - data:/usr/src/paperless/data
      - media:/usr/src/paperless/media
      - ./export:/usr/src/paperless/export
      - ./consume:/usr/src/paperless/consume
    env_file: docker-compose.env
    environment:
      PAPERLESS_REDIS: redis://broker:6379
      PAPERLESS_DBHOST: db
      PAPERLESS_TIKA_ENABLED: 1
      PAPERLESS_TIKA_GOTENBERG_ENDPOINT: http://gotenberg:3000
      PAPERLESS_TIKA_ENDPOINT: http://tika:9998

  gotenberg:
    image: docker.io/gotenberg/gotenberg:8.25
    restart: unless-stopped
    command:
      - "gotenberg"
      - "--chromium-disable-javascript=true"
      - "--chromium-allow-list=file:///tmp/.*"

  tika:
    image: docker.io/apache/tika:latest
    restart: unless-stopped

volumes:
  data:
  media:
  pgdata:
  redisdata:

Step 2: Create the Environment File

Create the docker-compose.env file that the webserver container reads. This file contains all the per-installation configuration that should not be baked into the compose file.

# UID and GID of the user running paperless inside the container.
# Set these to match your host user ID to avoid permission issues with
# the consume directory. Get your IDs with: id -u && id -g
USERMAP_UID=1000
USERMAP_GID=1000

# Required for public access. Set this to your Localtonet URL.
# Leave commented out for local-only access.
# PAPERLESS_URL=https://yoursubdomain.localto.net

# Secret key for cryptographic signing. Generate with:
# openssl rand -base64 64
# Must be changed before exposing Paperless publicly.
PAPERLESS_SECRET_KEY=change-me-use-openssl-rand-base64-64

# Your timezone. Used for correct timestamps on documents.
# Full list: https://en.wikipedia.org/wiki/List_of_tz_database_time_zones
PAPERLESS_TIME_ZONE=Europe/Istanbul

# The language used for OCR. Set this to the language most of your
# documents are written in. Use ISO 639-2 three-letter codes.
# eng=English, deu=German, fra=French, tur=Turkish, chi_sim=Simplified Chinese
PAPERLESS_OCR_LANGUAGE=eng

# Additional OCR languages to install (space-separated).
# Note: PAPERLESS_OCR_LANGUAGES (plural) = languages TO INSTALL
#       PAPERLESS_OCR_LANGUAGE  (singular) = language TO USE for OCR
# These are different variables. Do not confuse them.
# Example for Turkish + English:
# PAPERLESS_OCR_LANGUAGES=tur
# PAPERLESS_OCR_LANGUAGE=tur
# (English is installed by default, no need to add it here)

# Number of webserver worker processes. Increase for faster UI on
# multi-core systems. Each worker loads the full app into memory.
# Reduce to 1 on low-RAM systems (< 2 GB).
PAPERLESS_WEBSERVER_WORKERS=2

Step 3: Generate a Proper Secret Key

The placeholder change-me-use-openssl-rand-base64-64 in the env file must be replaced with an actual random key before you expose Paperless to the internet. Run this command and paste the output into the env file as the value of PAPERLESS_SECRET_KEY:

openssl rand -base64 64

xK9mP2nQ8rT5vW1yA4bE7hJ3kL6oU0iF9cG2dH5jM8nP1qR4sT7vX0yB3eI6lN9

This key is used to sign session cookies and tokens. If it changes after you have active sessions, all users will be logged out. If it leaks, attackers can forge authentication tokens. Keep it secret and back it up alongside your database.

Step 4: Start the Containers

With both files in place, pull the images and start the stack:

docker compose pull
docker compose up -d

[+] Pulling 5/5
 ✔ broker Pulled        2.1s
 ✔ db Pulled            4.3s
 ✔ gotenberg Pulled    12.8s
 ✔ tika Pulled         18.2s
 ✔ webserver Pulled    45.6s

[+] Running 5/5
 ✔ Container paperless-ngx-broker-1      Started
 ✔ Container paperless-ngx-db-1          Started
 ✔ Container paperless-ngx-gotenberg-1   Started
 ✔ Container paperless-ngx-tika-1        Started
 ✔ Container paperless-ngx-webserver-1   Started

Wait about 30 to 60 seconds for all containers to finish initializing, then check that everything is running:

docker compose ps

NAME                              STATUS
paperless-ngx-broker-1            running
paperless-ngx-db-1                running
paperless-ngx-gotenberg-1         running
paperless-ngx-tika-1              running
paperless-ngx-webserver-1         running

All five containers should show running. If any show exited or restarting, check the logs with docker compose logs webserver to see what went wrong.

Step 5: Create Your Admin Account

Open your browser and navigate to http://localhost:8000. On first access, Paperless-ngx prompts you to create an admin account. Fill in a username, email, and a strong password. This account has full access to all documents and settings.

docker compose exec webserver createsuperuser

If you prefer to create the account from the command line (useful for automated setups), you can also set PAPERLESS_ADMIN_USER, PAPERLESS_ADMIN_PASSWORD, and PAPERLESS_ADMIN_MAIL in docker-compose.env before first launch. Paperless will create the admin account automatically on startup.

Understanding the Interface: What Everything Does

Once logged in, you see the main document list. Before you start uploading documents, it is worth understanding the organizational structure that makes Paperless powerful.

Paperless-ngx uses machine learning to assign these automatically. Create a few correspondents, document types, and tags manually, then train the classifier by uploading 20 to 30 documents and assigning metadata manually. After that, new documents of similar types get tagged automatically.

Four Ways to Get Documents into Paperless-ngx

Supported file formats: PDF documents, JPEG, PNG, TIFF, GIF, BMP images, plain text files, and (with Tika/Gotenberg) Word, Excel, PowerPoint, OpenDocument files, and raw email files (.eml).

Exposing Paperless-ngx to the Internet with Localtonet

Paperless-ngx running locally is already useful, but its real value comes when you can access and add documents from anywhere: scan something at the office and have it appear in your home archive, or retrieve a document on your phone while standing in front of a bank teller.

To expose Paperless to the internet you need to forward inbound HTTPS traffic to port 8000 on your server. Localtonet handles this as an outbound tunnel, which means it works even behind NAT, CGNAT, or without a static IP address.

Step 1: Install and authenticate Localtonet

Download and install Localtonet on the same machine running Paperless-ngx. Follow the installation steps for your platform at localtonet.com and authenticate with your token. If you have already done this for another service, skip to Step 2.

Step 2: Create an HTTP tunnel to port 8000

In the Localtonet dashboard, create a new tunnel:

Your public URL will be something like https://mydocs.localto.net. Note this URL for the next step.

Step 3: Update the environment file with your public URL

Paperless-ngx needs to know its own public URL to generate correct links (for example, in email notifications and API responses). Open docker-compose.env and uncomment and set the PAPERLESS_URL line:

PAPERLESS_URL=https://mydocs.localto.net

Then restart the webserver container to apply the change:

docker compose restart webserver

Navigate to https://mydocs.localto.net in your browser. You should see the Paperless-ngx login page over HTTPS. Localtonet provides the TLS certificate automatically; you do not need to configure SSL yourself.

Connecting the Mobile App

With remote access configured, you can now use the Paperless mobile apps to scan and upload documents from your phone. Install the Paperless app for Android or iOS, then configure it:

Backing Up Paperless-ngx: What Needs to Be Saved

Your Paperless-ngx archive has value precisely because it contains important documents. A backup strategy is not optional. There are three things that need to be backed up:

The simplest reliable backup method: use the built-in document exporter, then back up the export directory. The exporter creates a complete JSON export of all metadata and copies all original document files into the export folder:

docker compose exec webserver document_exporter ../export

100%|██████████| 247/247 [00:04<00:00, 52.3it/s]

This puts everything into ~/paperless-ngx/export/. You can then sync this directory to another machine, an external drive, or cloud storage. To restore from an export:

docker compose exec webserver document_importer ../export

For a simpler day-to-day backup of the Docker volumes directly (no version constraints, but larger files):

# Stop containers first to ensure consistent backup
docker compose stop

# Backup media and database volumes
rsync -a /var/lib/docker/volumes/paperless-ngx_media/ ~/backup/media/
rsync -a /var/lib/docker/volumes/paperless-ngx_pgdata/ ~/backup/pgdata/

# Restart
docker compose start

Updating Paperless-ngx

Paperless-ngx releases updates frequently, including security fixes. The update process is straightforward:

# Always make a backup before updating
docker compose exec webserver document_exporter ../export

# Pull the new images
docker compose pull

# Restart with the new images (applies database migrations automatically)
docker compose up -d

Database migrations run automatically when the new webserver container starts. Do not stop the containers while a migration is in progress (watch for migration-related output in the logs with docker compose logs -f webserver).

Common Problems and Solutions

Frequently Asked Questions