Paperless-ngx

Description / name	Input element
Container Registry
Container Configuration Root Path
Timezone
User ID
Group ID
Paperless-ngx Host Port
Paperless-ngx /config Path
Paperless-ngx /config/media/documents Path

A community-supported open-source document management system that transforms your physical documents into a searchable online archive so you can keep, well, less paper.


Port	`8000`
Registry	`ghcr.io/daemonless/paperless-ngx`
Daemonless	daemonless/paperless-ngx
Source	paperless-ngx/paperless-ngx
Website	paperless-ngx.org

Version Tags

Tag	Description	Best For
`latest`	Upstream Binary. Built from official release.	Most users. Matches Linux Docker behavior.
Podman on FreeBSD currently requires root. All commands must be run as root (or via `doas`/`sudo`).

Before deploying, ensure your host environment is ready. See the Quick Start Guide for host setup instructions.

Deployment

Podman Compose Podman CLI Ansible

services:
  paperless-ngx:
    image: ghcr.io/daemonless/paperless-ngx:latest
    container_name: paperless-ngx
    environment:
      - PUID=1000
      - PGID=1000
      - TZ=UTC
      - PAPERLESS_ADMIN_USER=
      - PAPERLESS_ADMIN_PASSWORD=<PAPERLESS_ADMIN_PASSWORD>
    volumes:
      - "/path/to/containers/paperless-ngx:/config"
      - "/path/to/containers/paperless-ngx/config/media/documents:/config/media/documents"
    ports:
      - 8000:8000
      - 5555:5555
    restart: unless-stopped

podman run -d --name paperless-ngx \
  -p 8000:8000 \
  -p 5555:5555 \
  -e PUID=1000 \
  -e PGID=1000 \
  -e TZ=UTC \
  -e PAPERLESS_ADMIN_USER= \
  -e PAPERLESS_ADMIN_PASSWORD=<PAPERLESS_ADMIN_PASSWORD> \
  -v /path/to/containers/paperless-ngx:/config \
  -v /path/to/containers/paperless-ngx/config/media/documents:/config/media/documents \
  ghcr.io/daemonless/paperless-ngx:latest

- name: Deploy paperless-ngx
  containers.podman.podman_container:
    name: paperless-ngx
    image: ghcr.io/daemonless/paperless-ngx:latest
    state: started
    restart_policy: always
    env:
      PUID: "1000"
      PGID: "1000"
      TZ: "UTC"
      PAPERLESS_ADMIN_USER: ""
      PAPERLESS_ADMIN_PASSWORD: "<PAPERLESS_ADMIN_PASSWORD>"
    ports:
      - "8000:8000"
      - "5555:5555"
    volumes:
      - "/path/to/containers/paperless-ngx:/config"
      - "/path/to/containers/paperless-ngx/config/media/documents:/config/media/documents"

Interactive Configuration

Parameters

Environment Variables

Variable	Default	Description
`PUID`	`1000`	User ID for the application process
`PGID`	`1000`	Group ID for the application process
`TZ`	`UTC`	Timezone for the container
`PAPERLESS_ADMIN_USER`	``	Optional - Set name of the admin user on first start
`PAPERLESS_ADMIN_PASSWORD`	`<PAPERLESS_ADMIN_PASSWORD>`	Optional - Set password of the admin user on first start

Volumes

Path	Description
`/config`	Configuration directory
`/config/media/documents`	Optional - the actual document store (originals, archive and thumbnails)

Ports

Port	Protocol	Description
`8000`	TCP	Web UI
`5555`	TCP	Flower monitoring UI available at '/flower', optional

First time setup

To configure the admin user with a password during the first startup, you can define some additional environment variables in your container file:

services:
  paperlessngx:
    env:
      - PAPERLESS_ADMIN_USER=""
      - PAPERLESS_ADMIN_PASSWORD=""

These 2 variables can be removed after the initial was done and paperless won't change an existing admin user's password when these vars are defined.

Configuration

Configuration is best done using a .env file next to your compose.yaml. If no .env file is in compose.yaml, paperless-ngx will use default values.

Documents directory

If you want to keep your documents in a separate ZFS filesystem, you can mount it at /config/media/documents. This directoru should contain these 3 directories:

- archive
- originals
- thumbnails

Implementation Details

Architectures: amd64
User: bsd (UID/GID set via PUID/PGID). Defaults to 1000:1000.
Base: Built on ghcr.io/daemonless/base (FreeBSD 15.0).

Need help? Join our Discord community.