Paperless NGX

Paperless-ngx is a document management system that transforms your physical documents into a searchable online archive so you can keep, well, less paper. Paperless-ngx forked from paperless-ng to continue the great work and distribute responsibility of supporting and advancing the project among a team of people. Consider joining us! Discussion of this transition can be found in issues #1599 and #1632. A demo is available at demo.paperless-ngx.com using login demo / demo. Note: demo content is reset frequently and confidential information should not be uploaded.

Configuration

Type

Compose

Platform

linux

Env vars

PUID=1000PGID=1000TZ=America/New_YorkPAPERLESSURL=ADMIN_USER=ADMIN_PASS=RANDOMKEY=LANG=eng

Restart

unless-stopped

Source

Repo

Template by novaspirit·Source

Notes

Template created by Pi-Hosted Series
Check our Github page: https://github.com/pi-hosted/pi-hosted

Official Webpage: https://github.com/paperless-ngx/paperless-ngx
Official Docker Documentation: https://github.com/paperless-ngx/paperless-ngx

Services

broker

Configuration

Image

docker.io/library/redis:6.0

Volumes

/data : /portainer/Files/AppData/Config/paperless-ngx/redis/data

Restart

unless-stopped

Image details

Pulls: 11.0B

User: stackbrew

Created: Jun 05, 2014

Updated: 4 days ago

Status: active

webserver

Configuration

Image

ghcr.io/paperless-ngx/paperless-ngx:latest

Ports

8010:8000

Volumes

/usr/src/paperless/data : /portainer/Files/AppData/Config/paperless-ngx/data/usr/src/paperless/media : /portainer/Files/AppData/Config/paperless-ngx/media/usr/src/paperless/export : /portainer/Files/AppData/Config/paperless-ngx/export/usr/src/paperless/consume : /portainer/Files/AppData/Config/paperless-ngx/consume

Env vars

PAPERLESS_REDIS=redis://broker:6379USERMAP_UID=${PUID}USERMAP_GID=${PGID}PAPERLESS_TIME_ZONE=${TZ}PAPERLESS_URL=${PAPERLESSURL}PAPERLESS_SECRET_KEY=${RANDOMKEY}PAPERLESS_OCR_LANGUAGE=${LANG}PAPERLESS_ADMIN_USER=${ADMIN_USER}PAPERLESS_ADMIN_PASSWORD=${ADMIN_PASS}

Restart

unless-stopped

Installation

Ensure both Docker and Portainer are installed, and up-to-date
Log into your Portainer web UI
Under Settings → App Templates, paste the below URL
Head to Home → App Templates, and the list of apps will show up
Select the app you wish to deploy, fill in any config options, and hit Deploy

Template Import URL

https://raw.githubusercontent.com/Lissy93/portainer-templates/main/templates.json

Show Me

Service #1 - broker

docker run -d --name broker \
  -v /portainer/Files/AppData/Config/paperless-ngx/redis/data:/data \
  --restart=unless-stopped \
  docker.io/library/redis:6.0

Service #2 - webserver

docker run -d --name webserver \
  -p 8010:8000 \
  -e 'PAPERLESS_REDIS=redis://broker:6379' \
  -e 'USERMAP_UID=${PUID}' \
  -e 'USERMAP_GID=${PGID}' \
  -e 'PAPERLESS_TIME_ZONE=${TZ}' \
  -e 'PAPERLESS_URL=${PAPERLESSURL}' \
  -e 'PAPERLESS_SECRET_KEY=${RANDOMKEY}' \
  -e 'PAPERLESS_OCR_LANGUAGE=${LANG}' \
  -e 'PAPERLESS_ADMIN_USER=${ADMIN_USER}' \
  -e 'PAPERLESS_ADMIN_PASSWORD=${ADMIN_PASS}' \
  -v /portainer/Files/AppData/Config/paperless-ngx/data:/usr/src/paperless/data \
  -v /portainer/Files/AppData/Config/paperless-ngx/media:/usr/src/paperless/media \
  -v /portainer/Files/AppData/Config/paperless-ngx/export:/usr/src/paperless/export \
  -v /portainer/Files/AppData/Config/paperless-ngx/consume:/usr/src/paperless/consume \
  --restart=unless-stopped \
  ghcr.io/paperless-ngx/paperless-ngx:latest

If the stack expects env vars, set them or add them to a .env file first.

version: "3.4"
services:
  broker:
    image: docker.io/library/redis:6.0
    networks:
      - paperless_network
    restart: unless-stopped
    volumes:
      - /portainer/Files/AppData/Config/paperless-ngx/redis/data:/data

  webserver:
    image: ghcr.io/paperless-ngx/paperless-ngx:latest
    restart: unless-stopped
    depends_on:
      - broker
    ports:
      - 8010:8000
    healthcheck:
      test: ["CMD", "curl", "-fs", "-S", "--max-time", "2", "http://localhost:8000"]
      interval: 30s
      timeout: 10s
      retries: 5
    environment:
      PAPERLESS_REDIS: redis://broker:6379
      USERMAP_UID: ${PUID}
      USERMAP_GID: ${PGID}
      PAPERLESS_TIME_ZONE: ${TZ}
      PAPERLESS_URL: ${PAPERLESSURL}
      PAPERLESS_SECRET_KEY: ${RANDOMKEY}
      PAPERLESS_OCR_LANGUAGE: ${LANG}
      PAPERLESS_ADMIN_USER: ${ADMIN_USER}
      PAPERLESS_ADMIN_PASSWORD: ${ADMIN_PASS}
    networks:
      - paperless_network
    volumes:
      - /portainer/Files/AppData/Config/paperless-ngx/data:/usr/src/paperless/data
      - /portainer/Files/AppData/Config/paperless-ngx/media:/usr/src/paperless/media
      - /portainer/Files/AppData/Config/paperless-ngx/export:/usr/src/paperless/export
      - /portainer/Files/AppData/Config/paperless-ngx/consume:/usr/src/paperless/consume

networks:
  paperless_network:

Or, use the original compose file, straight from the template repo. Deploy with:

git clone https://github.com/pi-hosted/pi-hosted/
cd pi-hosted
docker compose -f stack/paperless-ngx.yml up -d

For more installation options, see the Documentation in our GitHub repo

Container Documentation

broker Documentation

Redis is the world’s fastest data platform for caching, vector search, and NoSQL databases.

Serve Paperless NGX on your own domain behind Caddy, Nginx or Traefik. Fill in your domain and copy the result. It's a starting point, some apps need their own base URL or extra headers set too.

Proxy Domain App port Upstream

Proxying paperless-ngx.example.com to http://webserver:8000

Add this to your Caddyfile

paperless-ngx.example.com {
	reverse_proxy http://webserver:8000
}

Check the logs first

Nine times out of ten the logs tell you exactly what went wrong.

In Portainer, go to Containers, click the container, then Logs. Or run docker logs <container>
Exit codes help too: 137 means killed, usually out of memory. 126 or 127 means the command inside the image is broken.

Port already in use

If deployment fails with "Bind for 0.0.0.0:8010 failed: port is already allocated", something else on your server is using that port.

Find what's using it: sudo ss -tlnp | grep :8010
Stop the other service, or pick a different host port. In 8010:8000 only the left number is yours to change, the right one belongs to the app.

Running but the page won't load

The container is up but nothing appears in your browser.

Use your server's real IP: http://your-server-ip:8010. The 0.0.0.0 link Portainer shows isn't a real address.
Give it a minute after first deploy, paperless-ngx can take a while to initialise.
Make sure your firewall allows the port, e.g. sudo ufw allow 8010

Permission denied on volumes

If the logs show "permission denied", the app can't write to its data folder on the host.

Fix the ownership: sudo chown -R 1000:1000 /portainer/Files/AppData/Config/paperless-ngx/redis/data (and the same for the other mapped folders)

Image won't pull

Test the pull directly on the host: docker pull docker.io/library/redis:6.0

"manifest unknown" means the tag no longer exists.
"toomanyrequests" is the Docker Hub rate limit. Log in with docker login to raise it.
"no space left on device" means a full disk. Reclaim space with docker system prune

"exec format error"

This means the image was built for a different CPU architecture than your server.

Check yours with uname -m: x86_64 is amd64, aarch64 is arm64. Raspberry Pi and other ARM boards are the usual culprits.

Container keeps restarting

The unless-stopped restart policy relaunches the app after every crash, so the real error can scroll past.

Check the logs right after a restart, the last few lines before it died are the useful ones.
Get the exit code with docker inspect <container> --format '{{.State.ExitCode}}'
Still stuck? Redeploy once with the restart policy set to no so the failure stays visible.

Stack won't deploy

Compose stacks fail fast on small mistakes, and Portainer shows the reason just above the editor.

YAML only accepts spaces for indentation, a single tab breaks the whole file.

Raise an issue

Found something which isn't working as it should? Here's how to report it.

Bug within the app: Open an issue within paperless-ngx's repo
Template not working: Open an issue on novaspirit/pi-hosted
This website not working: Open an issue on lissy93/portainer-templates

Similar apps

Anchor Productivity

Appsmith Productivity

Baikal Productivity Baserow (stack) Productivity

Blinko Productivity

Budibase Productivity

Codiad Productivity

CryptPad Productivity

Paperless NGX

Configuration

Notes

Services

broker

Configuration

Image details

webserver

Configuration

Installation

Via Portainer

Template Import URL

Docker Run

Service #1 - broker

Service #2 - webserver

Docker Compose

Alternative Methods

Container Documentation

broker Documentation

Proxy configurator

Troubleshooting

Check the logs first

Port already in use

Running but the page won't load

Permission denied on volumes

Image won't pull

"exec format error"

Container keeps restarting

Stack won't deploy

Raise an issue

Similar apps