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.

Version Tags

Parts

Before deploying, ensure your host environment is ready. See the Quick Start Guide for host setup instructions, including the security model for host vs. container privileges.

Deployment

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18

# 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

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36

name: paperless-ngx

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

    environment:
      - PUID=1000
      - PGID=1000
      - TZ=${TZ:-UTC}
      - PAPERLESS_REDIS=redis://${REDIS_HOSTNAME:-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

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11

# .env

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

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35

# appjail-director.yml

options:
  - alias:
  - ip4_inherit:
services:
  paperless-ngx:
    name: paperless_ngx
    options:
      - container: 'args:--pull'
    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}'
        - REDIS_DATA_LOCATION: !ENV '${REDIS_DATA_LOCATION}'
    volumes:
      - PAPERLESS_NGX_CONFIG_PATH: /config
  redis:
    name: redis
    options:
      - from: ghcr.io/daemonless/redis:latest
      - template: !ENV '${PWD}/template.conf'
    volumes:
      - redis_data: /config
volumes:
  PAPERLESS_NGX_CONFIG_PATH:
    device: '/containers/paperless-ngx'
  redis_data:
    device: !ENV '${REDIS_DATA_LOCATION}'

1
2
3
4
5
6
7

# Makejail

ARG tag=latest

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

Open http://<server>:8000 from another machine (the server's own browser can't use a published port).

Interactive Configuration

Parameters

Environment Variables

Volumes

Ports

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:

1
2
3
4
5

services:
  paperless-ngx:
    env:
      - PAPERLESS_ADMIN_USER=""
      - PAPERLESS_ADMIN_PASSWORD=""

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

Need help? Join our Discord community.