Bli papperslös med Paperless-ngx och Podman utan root

Det här sätter du upp

Paperless-ngx gör papper till ett sökbart arkiv. Du skannar eller fotograferar ett kvitto, en faktura eller ett brev, och Paperless läser texten (OCR), hittar datumet och sparar både din originalfil och en sökbar PDF-kopia. En sökning på "elnät" eller "förfallodatum" hittar sedan alla dokument som innehåller ordet. Den tar också emot Word-dokument och e-post.

Här körs den som en pod under en egen användare som heter paperless, bakom Caddy från Podman-guiden. Podden innehåller Paperless själv, PostgreSQL för databasen, Valkey för kön av uppgifter samt Apache Tika och Gotenberg, som läser Office-filer och e-post. Det är samma delar som Paperless egna installationsfiler använder.

Paperless-ngx är ett community-projekt som utvecklas av frivilliga i organisationen paperless-ngx på GitHub. Det är efterföljaren till de tidigare projekten Paperless och Paperless-ng. Det finns inget företag bakom det, och projektet anger inget land. Det är öppen källkod under GNU GPL v3: du får använda, ändra och dela det, och ändrade versioner som du delar måste ha samma licens. I vårt test kontaktade det ingen tjänst på internet av sig självt. Uppdateringskontrollen är avstängd från början; slår du på den frågar servern GitHubs API (api.github.com, som drivs av GitHub i USA) efter numret på senaste versionen. Den svenska språkdata som guiden använder installeras från Debians paketservrar (deb.debian.org) varje gång containern startar.

Varje steg nedan har körts på en nyinstallerad Melonslab VC-P Alloy (2 vCPU, 8 GB) med Debian 13:

• Administratörskontot skapades innan sidan kom ut på internet, och registreringen var stängd sedd utifrån.
• Svenska testdokument (ett skannat kvitto, en faktura på två sidor, ett brev fotograferat som JPEG, en Word-fil och ett e-postmeddelande) lästes rätt, å, ä och ö inräknade, och en sökning på ord som "förråd", "tvättstugan" och "Älvsbacka" hittade dem.
• OCR tog omkring 3,5 sekunder per sida med båda vCPU:erna, och en faktura på två sidor var sökbar omkring 11 sekunder efter uppladdningen.
• Dokument kom in via webbsidan på en skärm i mobilstorlek, och via SFTP och rsync till katalogen consume.
• Misslyckade inloggningar loggades med besökarens riktiga IP-adress, och inloggningsgränsen gällde per besökare.
• En fullständig export importerades till en ny, tom installation: alla dokument, sökningen och kontot med sitt lösenord kom tillbaka, och originalen var identiska byte för byte.
• Under sex minuters avlyssning av serverns trafik, i vila och under användning, öppnade Paperless inga utgående anslutningar.
• Allt startade igen av sig självt efter en omstart av servern.

Podden använde omkring 870 MB minne i vila. Paperless själv nådde som mest omkring 850 MB under OCR, och efter den första Word-filen och det första e-postmeddelandet låg Tika och Gotenberg kvar på omkring 220 och 240 MB.

Innan du börjar

Du behöver:

• en server uppsatt som i Podman-guiden, med Caddy igång;
• en A-post och en AAAA-post för paperless.example.com som pekar på din server;
• omkring 6 GB ledigt diskutrymme för avbilderna, plus ungefär dubbelt så mycket som dokumenten du ska spara.

Exemplen använder paperless.example.com för sidan och 198.51.100.7 för din egen IP-adress. Byt ut dem genomgående.

1. Skapa användaren

Som root:

useradd -m -s /bin/bash paperless
loginctl enable-linger paperless
machinectl shell paperless@

Allt fram till steg 5 körs som paperless.

2. Skapa hemligheterna

openssl rand -hex 24 | tr -d '\n' | podman secret create paperless-db-password -
openssl rand -base64 48 | tr -d '\n' | podman secret create paperless-secret-key -

Den första är databaslösenordet. Den andra, PAPERLESS_SECRET_KEY, signerar inloggningar och token, och Paperless kräver den.

3. Definiera podden

mkdir -p ~/.config/containers/systemd ~/consume ~/export
cd ~/.config/containers/systemd

~/consume är katalogen som Paperless hämtar nya dokument från, och ~/export är dit dess säkerhetskopior skrivs.

Skapa paperless.pod:

[Pod]
PodName=paperless
# Only Caddy, on this server, can reach Paperless: the port is not open to the internet.
PublishPort=127.0.0.1:8114:8000

[Install]
WantedBy=default.target

Skapa paperless-db.container:

[Container]
ContainerName=paperless-db
Image=docker.io/library/postgres:18
Pod=paperless.pod
Volume=paperless-db:/var/lib/postgresql
Environment=POSTGRES_DB=paperless POSTGRES_USER=paperless
Secret=paperless-db-password,type=env,target=POSTGRES_PASSWORD
AutoUpdate=registry

[Service]
Restart=always

Skapa paperless-broker.container:

[Container]
ContainerName=paperless-broker
Image=docker.io/valkey/valkey:9-alpine
Pod=paperless.pod
Volume=paperless-broker:/data
AutoUpdate=registry

[Service]
Restart=always

Skapa paperless-tika.container:

[Container]
ContainerName=paperless-tika
Image=docker.io/apache/tika:3.3.1.0
Pod=paperless.pod
AutoUpdate=registry

[Service]
Restart=always

Skapa paperless-gotenberg.container:

[Container]
ContainerName=paperless-gotenberg
Image=docker.io/gotenberg/gotenberg:8.37
Pod=paperless.pod
# Emails are turned into PDFs in a browser: no JavaScript, and no loading of images or trackers from the internet.
Exec=gotenberg --chromium-disable-javascript=true --chromium-allow-list=file:///tmp/.*
AutoUpdate=registry

[Service]
Restart=always

Och paperless-app.container:

[Unit]
After=paperless-db.service paperless-broker.service paperless-tika.service paperless-gotenberg.service

[Container]
ContainerName=paperless-app
Image=ghcr.io/paperless-ngx/paperless-ngx:latest
Pod=paperless.pod
Volume=paperless-data:/usr/src/paperless/data
Volume=paperless-media:/usr/src/paperless/media
Volume=%h/consume:/usr/src/paperless/consume
Volume=%h/export:/usr/src/paperless/export
Environment=USERMAP_UID=0 USERMAP_GID=0
Environment=PAPERLESS_URL=https://paperless.example.com
Environment=PAPERLESS_ALLOWED_HOSTS=paperless.example.com
Environment='PAPERLESS_PROXY_SSL_HEADER=["HTTP_X_FORWARDED_PROTO", "https"]'
Environment=PAPERLESS_ALLAUTH_TRUSTED_PROXY_COUNT=1
Environment=PAPERLESS_TIME_ZONE=Europe/Stockholm
Environment=PAPERLESS_DATE_ORDER=YMD
Environment=PAPERLESS_OCR_LANGUAGE=swe+eng PAPERLESS_OCR_LANGUAGES=swe
Environment=PAPERLESS_REDIS=redis://127.0.0.1:6379
Environment=PAPERLESS_DBENGINE=postgresql PAPERLESS_DBHOST=127.0.0.1
Environment=PAPERLESS_TIKA_ENABLED=1 PAPERLESS_TIKA_ENDPOINT=http://127.0.0.1:9998 PAPERLESS_TIKA_GOTENBERG_ENDPOINT=http://127.0.0.1:3000
Secret=paperless-db-password,type=env,target=PAPERLESS_DBPASS
Secret=paperless-secret-key,type=env,target=PAPERLESS_SECRET_KEY
AutoUpdate=registry

[Service]
Restart=always
TimeoutStartSec=900

Det här gör inställningarna:

• USERMAP_UID=0 kör Paperless som root i containern, vilket i rootless Podman är användaren paperless på servern. Filerna i ~/consume, ~/export och volymerna ägs då av paperless, så att du kan kopiera in dokument via SFTP och läsa exporterna utan extra steg.
• PAPERLESS_URL och PAPERLESS_ALLOWED_HOSTS talar om för Paperless vilken adress den har, så att inloggningen fungerar via Caddy och anrop till alla andra namn får 400. PAPERLESS_PROXY_SSL_HEADER talar om att Caddy levererar den över HTTPS, så att länkarna den skapar börjar med https://.
• PAPERLESS_ALLAUTH_TRUSTED_PROXY_COUNT=1 gör att Paperless tar besökarens adress från headern X-Forwarded-For, som Caddy sätter, för sin inloggningsgräns. Bara Caddy når porten, så headern går inte att förfalska. Steg 5 visar hur du kontrollerar det.
• PAPERLESS_OCR_LANGUAGES=swe installerar svenska för Tesseract, OCR-programmet, och PAPERLESS_OCR_LANGUAGE=swe+eng läser varje dokument som svenska och engelska. Utan svensk språkdata blev det "Bjorkvagen" och "férbrukning" på vår testfaktura, och en sökning på "förbrukning" hittade ingenting.
• PAPERLESS_DATE_ORDER=YMD passar svenska datum som 2026-09-30. Med standardvärdet, DMY, hittade Paperless inget datum i våra dokument och använde dagen för uppladdningen i stället.

Med Tika och Gotenberg kan Paperless läsa filer från Word, Excel och LibreOffice samt e-post (.eml). Deras avbilder tar 2,2 GB disk, och de använder omkring 170 MB minne i vila, och omkring 470 MB när de väl har konverterat en fil. Om du bara skannar papper kan du hoppa över deras två filer, raden med PAPERLESS_TIKA_ och deras namn på raden After=: enligt Paperless dokumentation tar den då bara emot PDF, bilder och ren text.

Starta podden:

systemctl --user daemon-reload
systemctl --user start paperless-pod
systemctl --user enable --now podman-auto-update.timer

Vid första starten laddas omkring 5,4 GB avbilder ner, vilket tog omkring tre minuter. Paperless är klar när loggen visar celery@paperless ready:

podman logs -f paperless-app

Tryck Ctrl+C för att sluta följa loggen.

4. Skapa ditt administratörskonto först

Så länge inget konto finns står det på Paperless registreringssida "This is the first user account for this installation and will be granted superuser privileges.", och den som öppnar sidan först får det kontot. Skapa ditt nu, innan Caddy lägger ut sidan på internet:

podman exec -it paperless-app python3 manage.py createsuperuser

Den frågar efter Username, Email address och lösenordet två gånger, och svarar Superuser created successfully. Efter det visar registreringssidan bara Sign Up Closed, och den förblir stängd: nya konton skapar du själv under Users & Groups.

5. Sätt Caddy framför

Gå tillbaka till root med exit, byt till Caddys användare med machinectl shell caddy@ och lägg till det här blocket sist i ~/Caddyfile:

paperless.example.com {
    reverse_proxy 127.0.0.1:8114
}

Starta om Caddy med systemctl --user restart caddy.

Kontrollera från din egen dator att registreringen är stängd:

curl -s https://paperless.example.com/accounts/signup/ | grep -o 'Sign Up Closed'

Logga sedan in på https://paperless.example.com med fel lösenord en gång, och titta i loggen som paperless:

podman exec paperless-app tail -n 2 /usr/src/paperless/data/log/paperless.log

[2026-10-02 18:53:39,224] [INFO] [paperless.auth] Login failed for user `anna` from IP `198.51.100.7`.

Står din egen adress där ser Paperless varje besökares riktiga IP-adress. I vårt test fick ett dussin misslyckade inloggningar från en adress svaret Too many failed login attempts. Try again later., men bara den adressen: en inloggning från en annan adress fungerade fortfarande.

6. Få in dokumenten

I webbläsaren. Välj Upload documents på Dashboard, eller släpp filer var som helst på sidan. Webbgränssnittet fungerar på en mobil: vi loggade in och laddade upp en JPEG på en skärm i mobilstorlek, och Upload documents öppnar mobilens egen filväljare. Paperless gör ingen egen mobilapp; appar från andra listas i projektets wiki, och dem har vi inte testat.

Via katalogen consume. Allt som kopieras till ~/consume tas in inom några sekunder och tas sedan bort från katalogen. Det passar en skanner eller ett skript. För att kopiera dit filer från din dator behöver din SSH-nyckel kunna logga in som paperless. Som root ger det här paperless samma nycklar som root:

install -d -m 700 -o paperless -g paperless /home/paperless/.ssh
install -m 600 -o paperless -g paperless /root/.ssh/authorized_keys /home/paperless/.ssh/

Sedan, från din dator:

rsync kvitto.pdf faktura.pdf paperless@paperless.example.com:consume/

Eller med SFTP, som de flesta filhanterare och skannerappar kan använda:

sftp paperless@paperless.example.com
sftp> put brev.pdf consume/

Via e-post. Paperless kan också hämta dokument från en brevlåda via IMAP, under Mail i menyn. Det har vi inte testat.

När ett dokument är klart dyker det upp under Documents. Öppna det för att se texten som Paperless läste på fliken Content, och datumet den hittade under Date created.

7. Sök på svenska

Sökrutan högst upp söker i texten i alla dokument. I vårt test hittade alla de här rätt dokument:

• "förråd", "tvättstugan", "Skruvdragare", "säkring" och "trädgårdsskötsel";
• "forrad" och "oberg", skrivna utan å, ä och ö, hittade också "förråd" och "Öberg";
• "764,78", ett belopp från en faktura.

OCR är inte felfri. På andra sidan av vår faktura gav liten text "pa" i stället för "på" och "vader" i stället för "väder", medan den större texten på första sidan lästes utan fel. En tydlig skanning i 300 dpi hjälper.

8. Här finns dina dokument

Paperless sparar upp till tre filer för varje dokument, i volymen paperless-media, ~/.local/share/containers/storage/volumes/paperless-media/_data/documents/:

• originals: filen precis som du laddade upp den, aldrig ändrad;
• archive: en PDF/A-kopia med den igenkända texten, som är den du söker i och laddar ner som standard;
• thumbnails: de små förhandsbilderna.

För skanningar är arkivkopian ungefär lika stor som originalet, så räkna med ungefär dubbla storleken på dina skanningar. Vår faktura på två sidor var 467 kB, arkivkopian 490 kB och förhandsbilden 12 kB. Databasen och sökindexet ligger i volymerna paperless-db och paperless-data.

9. Säkerhetskopiera

Paperless har en egen export, document_exporter, som skriver ut alla original, arkivkopior och förhandsbilder tillsammans med en manifest.json som innehåller databasen: dokument, taggar, användare med sina lösenordshashar och inställningar. Den går att importera till en ny installation. Förvara den lika säkert som själva dokumenten.

Som paperless skapar du ~/backup.sh:

#!/bin/sh
set -e
# Every document with its metadata, users and settings, in a form Paperless can import.
podman exec paperless-app document_exporter ../export --delete --no-progress-bar
# The database as well, as a second copy.
podman exec paperless-db pg_dump -U paperless paperless > ~/backup/paperless-db.sql

--delete tar bort filer ur exporten när du raderar dokumentet i Paperless, så att exporten stämmer med det du har. Sedan:

chmod 700 ~/backup.sh
mkdir -p ~/backup ~/.config/systemd/user

Skapa ~/.config/systemd/user/paperless-backup.service:

[Unit]
Description=Export Paperless-ngx for backup

[Service]
Type=oneshot
ExecStart=%h/backup.sh

Och ~/.config/systemd/user/paperless-backup.timer:

[Unit]
Description=Export Paperless-ngx every night

[Timer]
OnCalendar=*-*-* 23:30
Persistent=true

[Install]
WantedBy=timers.target

systemctl --user daemon-reload
systemctl --user enable --now paperless-backup.timer
systemctl --user start paperless-backup.service
ls ~/export ~/backup

Exporten körs 23.30, före Podmans uppdateringskontroll vid midnatt. Filerna ligger fortfarande på samma server, så kopiera /home/paperless/export och /home/paperless/backup till en annan maskin varje natt. Guiden om restic gör det, och dess säkerhetskopia av /home tar med båda.

10. Återställ

Så här återställde vi en fullständig export till en ny installation:

1. Sätt upp användaren, hemligheterna och podden som i steg 1 till 3, men skapa inget konto och lägg inte till Caddy-blocket än.
2. Kopiera din export till /home/paperless/export.
3. Importera den som paperless:

podman exec paperless-app document_importer ../export

Den kopierar filerna och bygger sedan om sökindexet. Lägg sedan till Caddy-blocket från steg 5 och logga in med ditt gamla konto och lösenord. I vårt test kom alla dokument, taggar och datum tillbaka, sökningen fungerade och originalen var identiska med dem vi laddade upp.

Importen fungerar bara i en tom Paperless. Dumpen paperless-db.sql är en andra kopia av databasen för PostgreSQL själv, om du någon gång skulle behöva den.

11. Uppdateringar

Alla containrar har AutoUpdate=registry, så timern från steg 3 letar varje natt efter nya avbilder och startar om podden om någon har ändrats. När Paperless startar på en ny version uppdaterar den sin databas själv. För att se vad den skulle uppdatera just nu:

podman auto-update --dry-run

paperless-ngx:latest följer varje ny version, även en ny huvudversion. PostgreSQL ligger kvar på version 18: en flytt till 19 kräver att dess data konverteras, vilket exporten och importen ovan klarar. Tika och Gotenberg är låsta till versionerna i Paperless egen Docker Compose-fil; när Paperless byter version där, ändra taggarna i dina två filer.

Efter en omstart av servern startade podden igen av sig själv, och Paperless var klar ungefär en och en halv minut senare. Varje start installerar den svenska språkdata på nytt, så Debians paketservrar måste gå att nå; Paperless startsteg tog 44 till 50 sekunder i vårt test.

Felsökning

Ett dokument får dagens datum i stället för sitt eget. Paperless använder det första datum i texten som den kan läsa och som inte ligger i framtiden. Kontrollera att PAPERLESS_DATE_ORDER=YMD är satt: med DMY läses datum som 2026-09-30 inte alls. I vårt brev kom datumet direkt efter ett ord, "Västerås 2026-09-30", och då missade Paperless det ändå. Rätta datumet under Date created och välj Save.

Loggen visar "Regular expression finditer timed out" när ett dokument tas in. Paperless ger sin datumsökning 0,1 sekunder, och på vår server med 2 vCPU tog den ibland längre tid. Dokumentet sparas ändå, med uppladdningsdatumet. Rätta datumet för hand som ovan.

Loggen visar "Login failed for user ... Unable to determine IP address." PAPERLESS_TRUSTED_PROXIES är satt. Då letar Paperless efter proxyns adress i X-Forwarded-For, men Caddys anslutning kommer från serverns egen adress och Caddy lägger inte till den där. Ta bort raden, behåll PAPERLESS_ALLAUTH_TRUSTED_PROXY_COUNT=1 och kör sedan systemctl --user daemon-reload och systemctl --user restart paperless-app.

Caddy svarar 502 en minut efter en omstart. Paperless startar fortfarande, med installationen av svenska. Vänta tills podman logs paperless-app visar celery@paperless ready.

Paperless kan inte installera svenska, och loggen visar "Unable to install language tesseract-ocr-swe as non-root". Containern körs som en annan användare än root, till exempel på grund av en rad UserNS=keep-id i podfilen. Använd USERMAP_UID=0 och USERMAP_GID=0 som i steg 3 i stället. Vi provade keep-id först: förutom det här fick det Podman att behålla en extra kopia av varje avbild, omkring 5 GB mer disk.