Ak si čítal môj článok o Paperless-ngx, vieš o čo ide. Tu je kompletný postup — tri kontajnery (Paperless, MariaDB, Redis), Gmail cez IMAP a prístup zvonka.

Čo potrebuješ

Predpoklady

Docker a Portainer nainštalované. Prístup cez SSH alebo File Manager. Na Synology odporúčam MariaDB namiesto SQLite — stabilnejšia pri väčšom množstve dokumentov.

1. Zisti UID a GID (Synology/Linux)

Paperless kontajner musí mať prístup k priečinkom. V SSH spusti:

id tvoje_meno

Výstup: uid=1026(tvoje_meno) gid=100(users). Hodnoty USERMAP_UID=1026 a USERMAP_GID=100 použiješ v compose.

2. Vytvor priečinky

Paperless potrebuje štyri priečinky — data, media, export a consume (nové dokumenty na spracovanie). Databáza MariaDB dostane vlastný priečinok.

mkdir -p /volume1/docker/paperless/data
mkdir -p /volume1/docker/paperless/media
mkdir -p /volume1/docker/paperless/export
mkdir -p /volume1/docker/paperless/consume
mkdir -p /volume1/docker/mariadb-paperless

3. Vygeneruj SECRET_KEY

Paperless vyžaduje náhodný tajný kľúč — minimálne 50 znakov. Vygeneruj ho na token generátore a skopíruj pred tým, ako zostavíš stack.

4. Docker Compose stack

V Portainer: Stacks → Add stack → Web editor. Vyber platformu:

services:

  paperless-broker:
    image: docker.io/library/redis:7
    container_name: paperless-broker
    restart: on-failure:5
    volumes:
      - /volume1/docker/paperless/data/redis:/data

  paperless-db:
    image: mariadb:10.11
    container_name: paperless-db
    restart: on-failure:5
    volumes:
      - /volume1/docker/mariadb-paperless:/var/lib/mysql
    environment:
      MARIADB_HOST: paperless
      MARIADB_DATABASE: paperless
      MARIADB_USER: paperless
      MARIADB_PASSWORD: paperless123       # ZMEŇ
      MARIADB_ROOT_PASSWORD: rootpass123   # ZMEŇ

  paperless-webserver:
    image: ghcr.io/paperless-ngx/paperless-ngx:latest
    container_name: paperless-webserver
    restart: on-failure:5
    depends_on:
      - paperless-db
      - paperless-broker
    ports:
      - 8010:8000
    volumes:
      - /volume1/docker/paperless/data:/usr/src/paperless/data
      - /volume1/docker/paperless/media:/usr/src/paperless/media
      - /volume1/docker/paperless/export:/usr/src/paperless/export
      - /volume1/docker/paperless/consume:/usr/src/paperless/consume
    environment:
      PAPERLESS_REDIS: redis://paperless-broker:6379
      PAPERLESS_DBENGINE: mariadb
      PAPERLESS_DBHOST: paperless-db
      PAPERLESS_DBNAME: paperless
      PAPERLESS_DBUSER: paperless
      PAPERLESS_DBPASS: paperless123       # ZMEŇ (rovnaké ako MARIADB_PASSWORD)
      PAPERLESS_DBPORT: 3306
      PAPERLESS_URL: https://paperless.tvoja-domena.xyz  # ZMEŇ
      PAPERLESS_SECRET_KEY: vloz-sem-vygenerovany-kluc-min-50-znakov  # ZMEŇ
      PAPERLESS_TIME_ZONE: Europe/Bratislava
      PAPERLESS_OCR_LANGUAGE: slk+ces+deu+eng
      PAPERLESS_OCR_USER_ARGS: '{"invalidate_digital_signatures": true}'
      USERMAP_UID: 1026   # ZMEŇ NA SVOJE UID (krok 1)
      USERMAP_GID: 100    # ZMEŇ NA SVOJE GID (krok 1)
⚠️ Čo musíš nahradiť v stacku

MARIADB_PASSWORD / PAPERLESS_DBPASS — rovnaké heslo, zmeň na bezpečné
MARIADB_ROOT_PASSWORD — root heslo pre MariaDB
PAPERLESS_URL — URL kde bude Paperless dostupný (napr. cez Cloudflare Tunnel)
PAPERLESS_SECRET_KEY — kľúč z kroku 3
USERMAP_UID/GID (Synology/Linux) — hodnoty z kroku 1

Klikni Deploy the stack a počkaj na "Success Stack successfully deployed". Prvé spustenie trvá 1–3 minúty.

5. Vytvor admin účet

V Portainer: Containers → paperless-webserver → Console → Connect. Spusti:

python3 manage.py createsuperuser

Zadaj meno, email a heslo. Alternatíva — pridaj do environment sekcie stacku pred prvým deployom:

PAPERLESS_ADMIN_USER: admin
PAPERLESS_ADMIN_PASSWORD: tvoje-heslo
PAPERLESS_ADMIN_MAIL: ty@example.com

Paperless vytvorí účet automaticky pri prvom spustení. Tieto riadky potom môžeš zo stacku odstrániť.

6. Prvé prihlásenie

Otvor http://192.168.1.100:8010 (nahraď IP svojho NAS). Prihlás sa admin účtom. Odporúčam skontrolovať:

  • Settings → General — URL a časová zóna
  • Settings → OCR — jazyky: slk+ces+deu+eng
  • Settings → Mail — prepojenie s Gmailom (krok 7)

7. Prepojenie s Gmailom (IMAP)

Paperless automaticky sťahuje prílohy z emailu. Potrebuješ Google App Password — bežné heslo nefunguje:

  1. Google účet → Security → 2-Step Verification → App passwords
  2. Vyber "Mail" → vygeneruj → skopíruj 16-znakový kód

V Paperless: Settings → Mail → Add mail account:

  • IMAP server: imap.gmail.com · Port: 993
  • Username: tvoj gmail · Password: App Password

Potom Add mail rule — filter podľa odosielateľa alebo predmetu, akcia Consume documents (attachments). Paperless bude pravidelne kontrolovať inbox.

8. Prístup zvonka — Cloudflare Tunnel

Pre prístup odkiaľkoľvek odporúčam Cloudflare Tunnel — bez otvárania portov. V Cloudflare Zero Trust vytvor public hostname napr. paperless.tvojadomena.sk → http://localhost:8010.

⚠️ PAPERLESS_URL musí súhlasiť s URL v prehliadači

Nastav PAPERLESS_URL presne na Cloudflare hostname — napr. https://paperless.tvojadomena.sk. Inak Paperless hádzí CSRF chyby pri prihlasovaní zvonka. Po zmene URL redeployuj stack.

9. Zálohovanie

Export všetkých dokumentov aj metadát do priečinka export:

docker exec paperless-webserver document_exporter ../export
⚠️ Zálohuj aj databázu

Zálohuj celý priečinok /volume1/docker/mariadb-paperless keď sú kontajnery zastavené, alebo použi mysqldump pre živú zálohu.

Troubleshooting

⚠️ Stránka sa nenačíta na :8010

Počkaj 2–3 minúty po deployi — Paperless inicializuje databázu pri prvom spustení. Logy: Portainer → Containers → paperless-webserver → Logs.

⚠️ Chyba pri pripojení na databázu

MariaDB ešte nebola plne pripravená. Reštartuj paperless-webserver v Portaineri po 1–2 minútach.

⚠️ CSRF error pri prihlasovaní

PAPERLESS_URL musí presne zodpovedať URL v prehliadači — vrátane https:// vs http://. Po zmene redeployuj stack.

⚠️ Gmail nesťahuje prílohy

Skontroluj: (1) App Password je správne bez medzier, (2) 2FA je zapnutá, (3) IMAP je povolený v Gmail: Settings → Forwarding and POP/IMAP → Enable IMAP.