Deploying Paperless-ngx with Traefik Labels and Accessing via DNS Entry

Introduction

In this post, we will show you how to deploy Paperless-ngx using Docker Compose and Traefik, and access it via a DNS entry like https://docs.your-domain.org. This configuration allows for a simple and secure deployment of your digital document management platform.

Introducing Traefik

Traefik is a dynamic reverse proxy and load balancer specifically designed for microservices and modern cloud-native applications. It enables automatic service discovery and management of SSL/TLS certificates. For more details and a comprehensive tutorial, visit our Traefik tutorial.

Introducing Paperless-ngx

Paperless-ngx is an open-source digital document management platform that allows you to digitize and efficiently manage paper documents. With Paperless-ngx, you can search, categorize, and store scanned documents in a central database. The platform offers a user-friendly interface and supports integration with various third-party tools.

Setting the DNS Entry

Before proceeding with the setup, ensure that the DNS entry for docs.your-domain.org is correctly set. This entry should point to the IP address of the server where Traefik is running. Use your DNS management service, such as Cloudflare, to add the appropriate entry.

Introducing Docker and Docker Compose

Docker allows applications to run in isolated containers, significantly simplifying their deployment and scaling. Docker Compose is a tool that lets you define and start multi-container applications. It helps manage complex application environments with a few commands.

Docker Compose for Paperless-ngx

Redis

The Redis service is used as a message broker for Paperless-ngx. Here are the relevant configuration details:

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

This section defines the Redis service, which acts as a fast, in-memory data structure server used by Paperless-ngx for message management. The configuration includes volume specification for data and assignment to the Paperless network.

PostgreSQL

The PostgreSQL service stores the data for Paperless-ngx. Here are the relevant configuration details:

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

This section defines the PostgreSQL database service, which acts as the data store for Paperless-ngx. The configuration includes volumes for data, environment variables for database configuration, and network assignment.

Paperless-ngx

The Paperless-ngx service provides the document management platform and is made accessible via Traefik:

  webserver:
    image: ghcr.io/paperless-ngx/paperless-ngx:latest
    restart: unless-stopped
    depends_on:
      - db
      - broker
    labels:
      - "traefik.enable=true"
      - "traefik.http.routers.paperless.rule=Host(`docs.your-domain.org`)"
      - "traefik.http.routers.paperless.entrypoints=websecure"
      - "traefik.http.routers.paperless.tls.certresolver=lets-encrypt"
      - "traefik.http.services.paperless.loadbalancer.server.port=8000"
    volumes:
      - data:/usr/src/paperless/data
      - media:/usr/src/paperless/media
      - ./export:/usr/src/paperless/export
      - ./consume:/usr/src/paperless/consume
    env_file: .env
    environment:
      PAPERLESS_REDIS: redis://broker:6379
      PAPERLESS_DBHOST: db
    networks:
      - paperless
      - web

This section defines the Paperless-ngx service, which depends on the PostgreSQL and Redis services. The configuration includes volume specifications for data, media, and various directories, as well as environment variables for connecting to the database and Redis server. The Traefik labels are crucial for correctly configuring the service and routing traffic accordingly.

Traefik

The Traefik labels are crucial for correctly configuring the service and routing traffic accordingly:

    labels:
      - "traefik.enable=true"
      - "traefik.http.routers.paperless.rule=Host(`docs.your-domain.org`)"  # Replace 'your-domain.org' with your actual domain
      - "traefik.http.routers.paperless.entrypoints=websecure"
      - "traefik.http.routers.paperless.tls.certresolver=lets-encrypt"
      - "traefik.http.services.paperless.loadbalancer.server.port=8000"
      - "traefik.docker.network=web"
    networks:
      - web
      - paperless

• traefik.enable=true: Enables Traefik for this service, allowing Traefik to monitor the service and route requests.
• traefik.http.routers.paperless.rule=Host('docs.your-domain.org'): Defines the URL mapping condition, specifying that requests to docs.your-domain.org are routed to the Paperless-ngx service.
• traefik.http.routers.paperless.entrypoints=websecure: Instructs Traefik to serve this service via the websecure entrypoint, used for HTTPS traffic.
• traefik.http.routers.paperless.tls.certresolver=lets-encrypt: Specifies that Traefik uses Let’s Encrypt to secure HTTPS traffic.
• traefik.http.services.paperless.loadbalancer.server.port=8000: Specifies the internal port of the Paperless-ngx service to which Traefik forwards traffic.
• traefik.docker.network=web: Specifies the Docker network used by Traefik to manage connections.

Networks

The network settings define the network Traefik uses to connect the services:

networks:
  web:
    external: true  # Uses an external network managed by Traefik
  paperless:

This section defines the networks used by Traefik and the Paperless-ngx services to connect the various services and manage connections.

Conclusion

With this guide, you can efficiently and securely deploy Paperless-ngx using Traefik and Docker. The configuration is flexible and can be easily adapted to individual requirements. For further questions or professional support, check out our Discord channel. We are happy to assist you with the optimal setup and management of your applications.

Complete Docker Compose

Here is the complete docker-compose.yml file for the Paperless-ngx installation:

version: "3.4"

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

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

  webserver:
    image: ghcr.io/paperless-ngx/paperless-ngx:latest
    restart: unless-stopped
    depends_on:
      - db
      - broker
    labels:
      - "traefik.enable=true"
      - "traefik.http.routers.paperless.rule=Host(`docs.your-domain.org`)"  # Replace 'your-domain.org' with your actual domain
      - "traefik.http.routers.paperless.entrypoints=websecure"
      - "traefik.http.routers.paperless.tls.certresolver=lets-encrypt"
      - "traefik.http.services.paperless.loadbalancer.server.port=8000"
      - "traefik.docker.network=web"
    volumes:
      - data:/usr/src/paperless/data
      - media:/usr/src/paperless/media
      - ./export:/usr/src/paperless/export
      - ./consume:/usr/src/paperless/consume
    env_file: .env


    environment:
      PAPERLESS_REDIS: redis://broker:6379
      PAPERLESS_DBHOST: db
    networks:
      - paperless
      - web

volumes:
  data:
  media:
  pgdata:
  redisdata:

networks:
  web:
    external: true
  paperless: