Paperless NGX Docker installation

Here comes order and overview of your files! The Paperless NGX Docker installation helps you to manage and find everything 👍

Warum Dokumenten Management ?!?!

Paperless document management offers immense benefits for both private users and companies. It goes far beyond the mere reduction of paper and fundamentally optimizes how information is managed and used.

I go into more detail in this article:

Paperless: Why document management and scope of services

in more detail. The bottom line is that more and more control and verification requirements are currently being introduced by law. This applies to money & assets, cryptos, pensions and even more so to emigrants.

Our “Paperless” project

Prerequisites

Linux, WINDOWS 10 / 11 with Docker

You can find installation instructions for Docker under WINDOWS WSL here

Install WINDOWS WSL and Docker Desktop

For the installation of Paperless-ngx a Docker Compose Setup was chosen to run all necessary services containerized. This includes the Paperless application itself, a PostgreSQL database, a Redis cache and the extensions Gotenberg for Office file conversions and Apache Tika for text recognition.

There are two important files in a project folder: an .env, in which sensitive settings such as database access data, passwords and external service URLs are stored, and docker-compose.yml, which defines and networks the containers.

The docker-compose.yml describes the services as follows:

• db: A PostgreSQL container that persistently stores data in a Docker volume.
• redis: A Redis server for the Paperless processing cache.
• webserver: The Paperless-ngx webserver container that provides the web interface and manages documents. It accesses the database and Redis and reads the .env variables.
• gotenberg: A container that converts Office files to PDF and is addressed by the Paperless server via an HTTP API.
• tika: An Apache Tika server container used for text recognition and content analysis.

The networks and volumes are defined in such a way that the services can communicate internally and the data remains persistent. The Paperless web interface can be accessed after starting via http://localhost:8010.

Documents can be placed in the consume/folder, where Paperless processes them automatically. Alternatively, documents can also be uploaded via the web interface, which is particularly useful for .eml files. For emails that only contain HTML, it is advisable to save them as PDF beforehand, as Paperless will otherwise display an error message due to “File type text/html not supported”.

Overall, the setup is designed in such a way that it is easy to expand, for example by automating the mail import or other conversion services. The configuration via .env makes it easy to adjust passwords and URLs without changing the compose file.

---

Example docker-compose.yml:

# version: "3.7"
services:
  dbpg:
    image: postgres:15-alpine
    volumes:
      - ./paperless_db:/var/lib/postgresql/data
    environment:
      POSTGRES_DB: paperless
      POSTGRES_USER: ${POSTGRES_USER}
      POSTGRES_PASSWORD: ${POSTGRES_PASSWORD}

  redis:
    image: redis:6-alpine    volumes:
      - ./redisdata:/data
  webserver:
    image: ghcr.io/paperless-ngx/paperless-ngx:latest
    depends_on:
      - dbpg
      - redis
      - gotenberg
      - tika
    ports:
      - "${PAPERLESS_PORT}:8000"
    environment:
      PAPERLESS_DBHOST: dbpg
      PAPERLESS_DBUSER: ${POSTGRES_USER}
      PAPERLESS_DBPASS: ${POSTGRES_PASSWORD}      PAPERLESS_SECRET_KEY: ${SECRET_KEY}
      PAPERLESS_FILENAME_FORMAT: "{{ correspondent }}/{{ created_year }}/{{ document_type }}/{{ title }}"
      PAPERLESS_OCR_LANGUAGE: deu
      PAPERLESS_TIKA_ENABLED: 1
      PAPERLESS_REDIS: redis://redis:6379/0
      PAPERLESS_GOTENBERG_URL: http://gotenberg:3000
      PAPERLESS_TIKA_URL: http://tika:9998
      PAPERLESS_EMAIL_ATTACHMENT_ONLY: ${PAPERLESS_EMAIL_ATTACHMENT_ONLY}
    volumes:
      - ./data:/usr/src/paperless/data      - ./consume:/usr/src/paperless/consume
      - ./export:/usr/src/paperless/export      - ./media:/usr/src/paperless/media
  gotenberg:
    image: gotenberg/gotenberg:latest
    ports:
      - "3000:3000"

  tika:
    image: ghcr.io/paperless-ngx/tika:latest    ports:      - "9998:9998"

---

The .env file

The .env file (environment file) is used to define environment variables that are read by applications – in this case Paperless NGX and its database – at startup. It is particularly useful for keeping sensitive information such as passwords or configuration details out of the main source code and easy to manage.

Here is an explanation of the lines provided:

• POSTGRES_USER=UserName This line specifies the username that Paperless NGX will use to connect to the PostgreSQL database. You should replace UserName with an actual username that you have set or want to set for the database.
• POSTGRES_PASSWORD=PasswordSecret The password for the PostgreSQL user named above is defined here. Be sure to replace PasswordSecret with a strong and secure password. This password is crucial for the security of your database.
• SECRET_KEY=777-76uz.hztd.UzZ6 The SECRET_KEY is a cryptographic key used by Paperless NGX (based on Django) for various security purposes, such as secure hash generation, password reset, or cookies. The string shown here is an example; you should replace this value with a truly random and unique string before deploying Paperless NGX in a production environment.
• PAPERLESS_PORT=8010 This variable specifies the port that the Paperless NGX web server is listening on within its container. By default, this is often 8000, but you can change it to another port such as 8010 to avoid conflicts or accommodate preferences. Note that this is the internal container port; port forwarding from your host system to the container is configured separately in your docker-compose.yml file.
• PAPERLESS_EMAIL_ATTACHMENT_ONLY=False This setting controls how Paperless NGX handles email attachments. If set to False (as here), Paperless NGX will not only process attachments, but may also attempt to interpret the body of the email itself as a document or extract metadata from it. If you set this value to True, Paperless NGX would only process email attachments and ignore the body of the email.

Important security note: The .env file contains sensitive information. Make sure that this file is never publicly accessible (e.g. not in a public Git repository). It should also not be copied directly into your container, but passed to the services as environment variables via Docker Compose.

POSTGRES_USER=BenutzerName
POSTGRES_PASSWORD=PasswortGeheimSECRET_KEY=777-76uz.hztd.UzZ6PAPERLESS_PORT=8010
PAPERLESS_EMAIL_ATTACHMENT_ONLY=False

---

You can start the project with:

docker-compose up -d

Paperless-ngx is then available at http://localhost:8010 and can be used.When starting for the first time, the containers are loaded first – this can take a few minutes. Starting Paperless (normally) also takes about 3 minutes. So don’t get nervous just because it doesn’t start immediately.

Link to support / donation for the channel
PayPal Link
Bank transfer, Bitcoin and Lightning

#PaperlessNGX #Docker #DocumentManagement #SelfHosted #Instruction #OpenSource #Paperless #Homelab #DMS #Installation #StepByStepInstruction