Skip to content

Paperless-ngx

Docker Compose deployment guide for Paperless-ngx on Ubuntu.

Paperless-ngx is a self-hosted document management system that helps organise, search and archive scanned documents and PDFs.

Official project:

Create the Project Folder

mkdir -p ~/docker/paperless
cd ~/docker/paperless

Create the Docker Compose File

Create:

nano docker-compose.yml

Paste:

services:
  paperless:
    image: ghcr.io/paperless-ngx/paperless-ngx:latest
    container_name: paperless

    ports:
      - "8000:8000"

    volumes:
      - ./data:/usr/src/paperless/data
      - ./media:/usr/src/paperless/media
      - ./consume:/usr/src/paperless/consume
      - ./export:/usr/src/paperless/export

    environment:
      - PAPERLESS_REDIS=redis://redis:6379

    depends_on:
      - redis

    restart: unless-stopped

  redis:
    image: redis:7
    container_name: paperless-redis
    restart: unless-stopped

Start Paperless-ngx

Run:

docker compose up -d

The first startup may take a few minutes while Paperless initializes its database and application files.

Create an Administrator Account

Once the containers are running, create an administrator account:

docker exec -it paperless python manage.py createsuperuser

Follow the prompts to create your username, email address, and password.

Access Paperless-ngx

Open:

http://YOUR_SERVER_IP:8000

Example:

http://192.168.1.50:8000

Log in using the administrator account you created.

Importing Documents

Paperless automatically watches the consume folder.

Any supported documents placed into:

./consume

will be imported and processed automatically.

Supported document types include:

  • PDF
  • JPEG
  • PNG
  • TIFF
  • Office documents
  • Many scanned document formats

Notes

  • OCR is enabled by default
  • Full-text search is built in
  • Automatic document tagging is supported
  • Reverse proxy + HTTPS is recommended for internet access
  • Regular backups of the data and media folders are recommended

Folder Structure

After installation, your Paperless folder may look similar to:

paperless/
├── docker-compose.yml
├── consume
├── data
├── export
└── media

Advanced Example (Reference Only)

This is my current Paperless-ngx deployment.

It includes additional services that are not required for a basic installation:

  • PostgreSQL database
  • Redis message broker
  • Apache Tika document processing
  • Gotenberg document conversion

These components improve compatibility with a wider range of document formats and provide a more scalable setup for larger document collections.

services:
  broker:
    image: docker.io/library/redis:7
    container_name: paperless-redis
    stop_grace_period: 90s
    restart: unless-stopped

    volumes:
      - ./redis:/data

  db:
    image: docker.io/library/postgres:16
    container_name: paperless-db
    stop_grace_period: 90s
    restart: unless-stopped

    volumes:
      - ./db:/var/lib/postgresql/data

    environment:
      POSTGRES_DB: paperless
      POSTGRES_USER: paperless
      POSTGRES_PASSWORD: your_secure_database_password

  gotenberg:
    image: docker.io/gotenberg/gotenberg:8
    container_name: paperless-gotenberg
    stop_grace_period: 60s
    restart: unless-stopped

  tika:
    image: docker.io/apache/tika:latest
    container_name: paperless-tika
    stop_grace_period: 60s
    restart: unless-stopped

  webserver:
    image: ghcr.io/paperless-ngx/paperless-ngx:latest
    container_name: paperless
    stop_grace_period: 60s
    restart: unless-stopped

    depends_on:
      - db
      - broker
      - gotenberg
      - tika

    ports:
      - "8456: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_DBPASS: your_secure_database_password
      PAPERLESS_TIKA_ENABLED: 1
      PAPERLESS_TIKA_GOTENBERG_ENDPOINT: http://gotenberg:3000
      PAPERLESS_TIKA_ENDPOINT: http://tika:9998

    restart: unless-stopped

Why My Setup Differs from the Basic Example

My production deployment uses PostgreSQL instead of the default SQLite database and adds Redis, Apache Tika, and Gotenberg.

These additional services provide:

  • Better scalability for larger document collections
  • Improved document conversion support
  • Enhanced text extraction and OCR workflows
  • More robust long-term operation

For most new users, the basic example earlier in this guide is sufficient and much easier to understand. This advanced example is included as a reference for readers who want to explore a more feature-complete deployment.

Conclusion

Paperless-ngx is one of the most useful self-hosted applications for managing documents, receipts, invoices, manuals, and scanned paperwork.

For many homelab users, it becomes the central repository for all household and technical documentation.