Paperless-ngx

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
Source	https://github.com/paperless-ngx/paperless-ngx
Website	https://paperless-ngx.org/

Version Tags

Tag	Description	Best For
latest	Built from latest upstream release and latest FreeBSD packages.	Most users — recommended.

Parts

Service	Image	Role
paperlessngx	ghcr.io/daemonless/paperless-ngx:latest		docs
redis	ghcr.io/daemonless/redis:latest		docs

Prerequisites

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

Deployment

Podman Compose

1. Save as .env and fill in what is empty:

# Paperless-ngx for FreeBSD (Daemonless)
# Copy to .env and edit. Any PAPERLESS_* setting from
# https://docs.paperless-ngx.com/configuration/ can be added here.

# Where data lives on the host
CONFIG_LOCATION=/containers/paperless-ngx/config
REDIS_DATA_LOCATION=/containers/paperless-ngx/redis

# Optional: keep the document store (originals, archive, thumbnails) elsewhere,
# e.g. on its own ZFS filesystem. Leave unset to keep it under CONFIG_LOCATION.
# DOCUMENTS_LOCATION=/containers/paperless-ngx/documents

# Admin user created on first start (remove after setup)
PAPERLESS_ADMIN_USER=admin
PAPERLESS_ADMIN_PASSWORD=

# Timezone (TZ identifier)
# TZ=UTC

2. Save as compose.yaml:

name: paperless-ngx

services:
  paperlessngx:
    image: ghcr.io/daemonless/paperless-ngx:latest
    restart: unless-stopped
    network_mode: host

    environment:
      - PUID=1000
      - PGID=1000
      - TZ=${TZ:-UTC}
      - PAPERLESS_REDIS=redis://localhost:6379
      - PAPERLESS_ADMIN_USER=${PAPERLESS_ADMIN_USER}
      - PAPERLESS_ADMIN_PASSWORD=${PAPERLESS_ADMIN_PASSWORD}

    env_file:
      - .env

    depends_on:
      - redis

    volumes:
      - ${CONFIG_LOCATION}:/config

    ports:
      - 8000:8000
      - 5555:5555

  redis:
    image: ghcr.io/daemonless/redis:latest
    restart: unless-stopped
    network_mode: host
    volumes:
      - /etc/localtime:/etc/localtime:ro
      - ${REDIS_DATA_LOCATION}:/config

Then run podman-compose up -d.

AppJail Director

.env:

# .env

DIRECTOR_PROJECT=paperless-ngx
PUID=1000
PGID=1000
TZ=UTC
PAPERLESS_REDIS=redis://localhost:6379
PAPERLESS_ADMIN_USER=admin
PAPERLESS_ADMIN_PASSWORD=<PAPERLESS_ADMIN_PASSWORD>
CONFIG_LOCATION=/containers/paperless-ngx/config
DOCUMENTS_LOCATION=
REDIS_DATA_LOCATION=/containers/paperless-ngx/redis

appjail-director.yml:

# appjail-director.yml

options:
  - alias:
  - ip4_inherit:
services:
  paperless-ngx:
    name: paperless_ngx
    options:
      - container: 'args:--pull'
      - expose: '8000:8000 proto:tcp'
      - expose: '5555:5555 proto:tcp'
    oci:
      user: root
      environment:
        - PUID: !ENV '${PUID}'
        - PGID: !ENV '${PGID}'
        - TZ: !ENV '${TZ}'
        - PAPERLESS_REDIS: !ENV '${PAPERLESS_REDIS}'
        - PAPERLESS_ADMIN_USER: !ENV '${PAPERLESS_ADMIN_USER}'
        - PAPERLESS_ADMIN_PASSWORD: !ENV '${PAPERLESS_ADMIN_PASSWORD}'
        - CONFIG_LOCATION: !ENV '${CONFIG_LOCATION}'
        - DOCUMENTS_LOCATION: !ENV '${DOCUMENTS_LOCATION}'
        - REDIS_DATA_LOCATION: !ENV '${REDIS_DATA_LOCATION}'
    volumes:
      - paperless-ngx: /config
  paperless-redis:
    name: paperless_redis
    options:
      - from: ghcr.io/daemonless/redis:latest
      - template: !ENV '${PWD}/template.conf'
    volumes:
      - redis_data: /config
volumes:
  paperless-ngx:
    device: '/containers/paperless-ngx'
  redis_data:
    device: !ENV '${REDIS_DATA_LOCATION}'

Makejail:

# Makejail

ARG tag=latest

OPTION container=boot
OPTION overwrite=force
OPTION from=ghcr.io/daemonless/paperless-ngx:${tag}

Save the files above, then run appjail-director up.

Warning

Exposing ports in AppJail means that your service can be reached from remote hosts. If that is not your intention, do not expose the ports and communicate with the service using the jail's IPv4 address or hostname assigned by the virtual network.

To avoid exposing ports, just remove the expose option in your appjail-director.yml or from your command-line arguments.

Access at: http://localhost:8000

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_REDIS	redis://localhost:6379
PAPERLESS_ADMIN_USER	admin	Set name of the admin user on first start
PAPERLESS_ADMIN_PASSWORD	<PAPERLESS_ADMIN_PASSWORD>	Set password of the admin user on first start
CONFIG_LOCATION	/containers/paperless-ngx/config	Path to store configuration, database and (by default) documents
DOCUMENTS_LOCATION	``	Optional separate document store (originals, archive, thumbnails), e.g. its own ZFS filesystem
REDIS_DATA_LOCATION	/containers/paperless-ngx/redis	Path to store the redis data

Volumes

Path	Description
/config	Configuration directory

Ports

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

Upgrade to v3

Pre-Requisites

Upgrading to Paperless-ngx v3 can only be performed from version 2.20.15. If you are running an older version, please upgrade to v2.20.15 before proceeding with the v3 upgrade.

Breaking Changes

Paperless-ngx v3 introduced some changes to the configuration. Read the official v3 Migration Guide to make sure you adapt your configuration so that it works with v3.

Database migration

The DB migration will run automatically when the container starts.

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:

- archive
- originals
- thumbnails

Architectures: amd64 User: bsd (UID/GID via PUID/PGID, defaults to 1000:1000) Base: FreeBSD 15

---

Need help? Join our Discord community.