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.

Root Privileges Required

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  # User ID for the application process
      - PGID=1000  # Group ID for the application process
      - TZ=UTC  # Timezone for the container
      - PAPERLESS_ADMIN_USER=admin  # 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/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=admin \
  -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: "admin"
      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"

Access at: http://localhost:8000

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`	`admin`	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 setup 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:

1
2
3

- 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.1).

Need help? Join our Discord community.