Paperless-ngx on a Seedbox: A Home for Your Documents

Why Paperless-ngx on an Appbox

Paperless-ngx ingests your scans, letters, invoices and receipts, runs OCR over them, and gives you a searchable, tagged archive you will actually use. It is the kind of app that should be reachable from everywhere and backed by real storage, which makes an appbox a natural home: automatic HTTPS on its own subdomain, included disk space, and no home server to babysit.

This is the exact setup we tested end to end on our platform, including dropping a PDF into the consume folder and watching it get OCRed and archived. Replace USERNAME with your panel username in lowercase and SERVER with your server name; your appbox page shows both. New to containers on your appbox? Skim Run Your Own Docker Containers on a Seedbox first.

The Setup

mkdir -p ~/apps/paperless/{data,media,export,consume}
cd ~/apps/paperless

Create ~/apps/paperless/docker-compose.yml:

name: paperless

services:
  broker:
    container_name: paperless-broker
    image: docker.io/valkey/valkey:9-alpine
    restart: unless-stopped
    volumes:
      - redisdata:/data

  webserver:
    container_name: paperless-webserver
    image: ghcr.io/paperless-ngx/paperless-ngx:latest
    restart: unless-stopped
    depends_on:
      - broker
    volumes:
      - ./data:/usr/src/paperless/data
      - ./media:/usr/src/paperless/media
      - ./export:/usr/src/paperless/export
      - ./consume:/usr/src/paperless/consume
    env_file: docker-compose.env
    environment:
      PAPERLESS_REDIS: redis://broker:6379
      PAPERLESS_DBENGINE: sqlite
    networks:
      - default
      - traefik_USERNAME
    labels:
      - traefik.enable=true
      - traefik.docker.network=traefik_USERNAME
      - traefik.http.routers.paperless.rule=Host(`paperless.USERNAME.SERVER.bysh.me`)
      - traefik.http.routers.paperless.entrypoints=web
      - traefik.http.services.paperless.loadbalancer.server.port=8000

volumes:
  redisdata:

networks:
  traefik_USERNAME:
    external: true

And ~/apps/paperless/docker-compose.env:

# Keeps every file the app writes owned by you on the host,
# which is what makes the consume folder usable over SFTP.
USERMAP_UID=0
USERMAP_GID=0

# Must be your exact public URL or logins fail behind the proxy.
PAPERLESS_URL=https://paperless.USERNAME.SERVER.bysh.me

PAPERLESS_SECRET_KEY=put-a-long-random-string-here
PAPERLESS_TIME_ZONE=Europe/Amsterdam
PAPERLESS_OCR_LANGUAGE=eng

# Your admin account, created on first start.
PAPERLESS_ADMIN_USER=USERNAME
PAPERLESS_ADMIN_PASSWORD=pick-a-strong-password

Generate the secret with openssl rand -hex 32 and paste it in. The two mappings at the top matter on our platform: without them the app locks you out of your own consume folder.

Start it:

docker compose up -d

The download is about 2.5 GB, and the first boot takes around three minutes while it runs migrations and builds its index. The container reports health: starting that whole time; wait for healthy in docker ps rather than restarting it.

Using It

Open https://paperless.USERNAME.SERVER.bysh.me and log in with the admin account from your env file. Upload documents through the web UI, or drop PDFs and scans into ~/apps/paperless/consume (SFTP works fine); they get OCRed, indexed, and filed automatically within half a minute, and the original is archived under ~/apps/paperless/media. There are also solid mobile apps (Paperless Mobile on both platforms) that talk to your server URL.

Good to Know

• Idle footprint is around three quarters of a gigabyte of memory, mostly its OCR and task workers. Fine on our standard appboxes, just know it is not a tiny app.
• Everything durable lives in the one ~/apps/paperless folder, so backing that folder up is the whole backup story.
• One log line will say the worker runs with superuser privileges; on our rootless Docker that container root is just your own unprivileged user, so it is expected and harmless.
• Upgrades: docker compose pull && docker compose up -d.
• To remove it: docker compose down -v, then delete ~/apps/paperless.

Questions or stuck halfway? Open a ticket, we have run this exact stack ourselves.