Kör Stirling-PDF, din egen PDF-verktygslåda, med Podman utan root

Det här sätter du upp

För att slå ihop två PDF:er eller krympa en skanning laddar många upp avtal, id-kort och fakturor till gratis PDF-sajter, och de sajterna får en kopia av varje fil. Stirling-PDF gör samma jobb i din webbläsare, på din egen server: över 50 verktyg, bland annat för att slå ihop, dela och komprimera, OCR som gör skannade sidor sökbara, och konvertering från Word till PDF.

Här körs den från sin officiella avbild, i Podman under en egen användare som heter stirling, bakom Caddy från Podman-guiden.

Stirling-PDF utvecklas av Stirling PDF, Inc., ett företag i San Francisco i USA, med bidrag från sin community på GitHub. Den är open core: det mesta av koden är öppen källkod under MIT-licensen, medan katalogerna app/proprietary, app/saas, engine och delar av webbgränssnittet omfattas av den proprietära Stirling PDF User License. De officiella avbilderna innehåller de delarna, och inloggningen och användarhanteringen som används nedan kommer därifrån. Utan betald licens tillåter den licensen "internal trial, evaluation, or minimal use" inom de gränser programmet sätter, som här är fem användarkonton, och inte användning i kundnära eller kommersiella sammanhang. Ska du använda den i ett företag, läs villkoren först.

Som standard frågar Stirling-PDF administratören vid första inloggningen om analys ska slås på, som skickas till PostHogs servrar i EU (eu.i.posthog.com) och till en spårningspixel hos Scarf, och när en administratör öppnar den kontrollerar webbläsaren uppdateringar hos supabase.stirling.com, en tjänst hos Stirling, och skickar då versionen, utgåvan och om inloggning är på. Den här guiden stänger av båda före första starten.

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

• Utan inloggning svarade verktygen 401 från internet, och standardkontot admin med lösenordet stirling fanns aldrig, eftersom guiden skapar ditt eget administratörskonto i stället.
• På 2 vCPU tog det 3 sekunder att slå ihop en fil på 35 MB med en skanning och 13 sekunder att komprimera den till 9 MB. OCR av ett skannat hyresavtal på en sida tog 4 sekunder, och av fem sidor 9 sekunder, med å, ä och ö rätt. En Word-fil blev en PDF på under en sekund, eller på 10 sekunder när LibreOffice först behövde starta.
• En PDF på 50 MB gick igenom Caddy utifrån, och en på 120 MB stoppades.
• Under en inspelning av nätverkstrafiken genom tre omstarter, en inloggning och OCR i webbläsaren öppnade Stirling-PDF inga anslutningar mot internet, och webbläsaren kontaktade bara servern.
• Efter varje åtgärd var containerns tillfälliga katalog tom igen, och inga filnamn sparades.
• En uppdatering med podman auto-update, en säkerhetskopia och en återställning fungerade, och allt startade igen av sig självt efter en omstart av servern.

Stirling-PDF använde omkring 1 GB minne i vila, omkring 1,4 GB under OCR och som mest 1,7 GB när den komprimerade en fil på 35 MB.

Innan du börjar

Du behöver:

• en server uppsatt som i Podman-guiden, med Caddy igång;
• omkring 2,5 GB ledigt diskutrymme för avbilden;
• en A-post och en AAAA-post för pdf.example.com som pekar på din server.

Exemplen använder pdf.example.com för Stirling-PDF och anna för ditt administratörskonto. Byt ut dem genomgående.

1. Skapa användaren

Som root:

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

Allt fram till steg 5 körs som stirling.

2. Lägg till svenska för OCR

Avbilden läser text på engelska, tyska, franska, portugisiska och kinesiska. För svenska laddar du ner Tesseracts svenska språkdata till en katalog som containern läser:

mkdir -p ~/tessdata
curl -fL -o ~/tessdata/swe.traineddata https://github.com/tesseract-ocr/tessdata_fast/raw/main/swe.traineddata

Filen är omkring 4 MB. Andra språk fungerar på samma sätt, med sin kod på tre bokstäver, som nor, dan eller fin. På vårt testavtal blev "Hyresgäst: Åsa Öberg" till "Hyresgast: Asa Oberg" med engelsk OCR, och med svenska blev varje bokstav rätt.

3. Välj ditt administratörskonto

När Stirling-PDF startar första gången skapar den ett administratörskonto som heter admin med lösenordet stirling, och API:et godtar det lösenordet direkt, innan någon har bytt det. Den som hittar din server före dig skulle kunna logga in. Låt den skapa ditt eget konto i stället. Skapa ~/stirling.env, med ett eget långt lösenord:

cat > ~/stirling.env <<'EOF'
SECURITY_INITIALLOGIN_USERNAME=anna
SECURITY_INITIALLOGIN_PASSWORD=ett-eget-langt-losenord
EOF
chmod 600 ~/stirling.env

Stirling-PDF läser bara de här raderna när kontot inte finns än. Behåll filen: om databasen någon gång försvinner skapar den ditt konto igen från filen, i stället för admin.

4. Definiera containern

mkdir -p ~/.config/containers/systemd

Skapa ~/.config/containers/systemd/stirling-pdf.container:

[Unit]
Description=Stirling-PDF

[Container]
ContainerName=stirling-pdf
Image=docker.io/stirlingtools/stirling-pdf:latest
Volume=stirling-configs:/configs
# Extra OCR languages, copied into the container at every start
Volume=%h/tessdata:/usr/share/tessdata:ro
# Your admin account, created at the first start
EnvironmentFile=%h/stirling.env
Environment=SECURITY_ENABLELOGIN=true
# No analytics, no update check, no record of your files
Environment=SYSTEM_ENABLEANALYTICS=false
Environment=SYSTEM_SHOWUPDATE=false
Environment=PREMIUM_ENTERPRISEFEATURES_AUDIT_ENABLED=false
Environment=SYSTEM_FILEUPLOADLIMIT=100MB
# Only Caddy, on this server, can reach Stirling-PDF: the port is not open to the internet.
PublishPort=127.0.0.1:8105:8080
AutoUpdate=registry

[Service]
Restart=always
# The first start downloads about 2.3 GB.
TimeoutStartSec=900

[Install]
WantedBy=default.target

Vad raderna gör:

• Avbilden latest innehåller Tesseract och OCRmyPDF för OCR, och LibreOffice för Word-, Excel- och PowerPoint-filer. Den är 2,34 GB. latest-fat (2,51 GB) lägger till fler typsnitt och Stirlings AI-motor, och latest-ultra-lite (580 MB) saknar OCR och LibreOffice, de två saker de flesta installerar den för.
• stirling-configs innehåller inställningarna och databasen med användarkontona. Dina PDF:er sparas aldrig där.
• SECURITY_ENABLELOGIN=true kräver inloggning för webbgränssnittet och för API:et. Det är standard i version 3, och raden ser till att det förblir så.
• SYSTEM_ENABLEANALYTICS=false stänger av PostHog och Scarf för hela servern, så att frågan om analys aldrig visas. SYSTEM_SHOWUPDATE=false hindrar webbläsare från att fråga supabase.stirling.com om uppdateringar; timern i steg 9 håller avbilden uppdaterad i stället.
• PREMIUM_ENTERPRISEFEATURES_AUDIT_ENABLED=false stänger av granskningsloggen. Den är på som standard, även utan licens, och sparar varje åtgärd i 90 dagar, med användaren, dennes IP-adress och namn och storlek på varje fil.
• SYSTEM_FILEUPLOADLIMIT=100MB stoppar större uppladdningar i Stirling-PDF självt. Caddy får samma gräns i steg 5.

Starta den:

systemctl --user daemon-reload
systemctl --user start stirling-pdf
systemctl --user enable --now podman-auto-update.timer

Den första starten laddar ner avbilden, och sedan behöver Stirling-PDF omkring 35 sekunder innan den svarar. Kontrollera att den är igång:

curl -s http://127.0.0.1:8105/api/v1/info/status

Den svarar {"version":"3.0.2","status":"UP"}.

5. Sätt Caddy framför

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

pdf.example.com {
    request_body {
        max_size 100MB
    }
    reverse_proxy 127.0.0.1:8105
}

Starta om Caddy med systemctl --user restart caddy.

Caddy har ingen egen gräns för uppladdningar, så max_size sätter en som stämmer med steg 4. Vill du tillåta större filer höjer du båda.

6. Kontrollera att obehöriga hålls ute

Prova ett verktyg utan att logga in, från din egen dator:

curl -s -o /dev/null -w '%{http_code}\n' -F fileInput=@any.pdf https://pdf.example.com/api/v1/misc/compress-pdf

Svaret är 401. Inloggning med admin och stirling misslyckas också. Utan konto ser en besökare inloggningssidan, beskrivningen av API:et och versionsnumret, och inget annat.

Öppna https://pdf.example.com och logga in med kontot från steg 3. Stirling-PDF loggar varje felaktigt lösenord med besökarens riktiga adress, som Caddy skickar vidare.

Efter fler än fem felaktiga lösenord i rad låses kontot i två timmar, även för rätt lösenord. Det kan vem som helst som känner till ditt användarnamn åstadkomma, så välj ett som inte är lätt att gissa. En omstart av containern häver låsningen.

Utan licens rymmer servern fem konton totalt. Knappen Invite längst ner till vänster öppnar Users, som visar hur många som används, och med Invite people lägger du till fler.

7. Använd verktygen

Verktygen finns till höger. Välj ett, lägg till filer med Add Files, kontrollera inställningarna och kör det med knappen längst ner i panelen. När det är klart sparar du resultatet med Download.

Så här OCR-tolkar du ett skannat svenskt dokument:

1. Välj OCR / Cleanup scans och lägg till skanningen.
2. Under Languages markerar du Swedish, och avmarkerar English om dokumentet bara är på svenska.
3. Välj Process OCR and Review och sedan Download.

Resultatet ser ut som skanningen, men du kan söka i det och kopiera texten. I vårt test blev paragraftecknet § siffran 8, så kontrollera siffror och tecken i viktiga dokument.

För att göra en Word-fil till en PDF väljer du Convert, lägger till filen, kontrollerar att Convert to: är Document (PDF) och väljer Convert Files.

Det här är tiderna vi mätte på 2 vCPU, från servern via Caddy:

LibreOffice startar vid den första konverteringen och stängs igen efter två minuter utan någon.

8. Vad som sparas var

• På servern: varje uppladdning skrivs till en tillfällig katalog i containern medan den bearbetas och raderas efteråt. I våra tester var katalogen tom igen efter varje åtgärd, och själva containern ersätts vid varje omstart. Namnen på Word- och andra Office-filer som du konverterar syns i loggen, journalctl --user -u stirling-pdf, men aldrig deras innehåll.
• I din webbläsare: PDF Library till vänster sparar dina filer, både original och resultat, i webbläsarens egen lagring på din dator, inte på servern. På en delad dator raderar du dem där när du är klar.

9. Uppdateringar

podman-auto-update.timer från steg 4 letar en gång om dagen efter en ny latest-avbild och startar om Stirling-PDF med den. För att se om en väntar, som stirling:

podman auto-update --dry-run

pending i kolumnen UPDATED betyder att en uppdatering väntar, och podman auto-update installerar den direkt. I vårt test tog en uppdatering från 3.0.0 till 3.0.2 några sekunder, och kontot och inställningarna fanns kvar. För att frigöra diskutrymmet för gamla avbilder efteråt:

podman image prune -f

10. Säkerhetskopiera

Dina PDF:er sparas aldrig på servern, så det finns lite att säkerhetskopiera: inställningarna, användarkontona och nyckeln som krypterar sparade inloggningsuppgifter. Som stirling:

mkdir -p ~/backup
systemctl --user stop stirling-pdf
podman volume export stirling-configs --output ~/backup/stirling-configs.tar
systemctl --user start stirling-pdf
chmod 600 ~/backup/stirling-configs.tar

Kopiera ~/backup till en annan maskin och förvara den säkert. Så här återställer du den:

systemctl --user stop stirling-pdf
podman volume rm stirling-configs
podman volume create stirling-configs
podman volume import stirling-configs ~/backup/stirling-configs.tar
systemctl --user start stirling-pdf

Felsökning

Swedish saknas i listan under Languages, eller OCR gör å, ä och ö till a, a och o. Filen från steg 2 saknas, eller så var Swedish inte markerat. Kontrollera att ~/tessdata/swe.traineddata finns och starta om Stirling-PDF med systemctl --user restart stirling-pdf, eftersom språkfilerna kopieras in vid start.

En stor uppladdning misslyckas, eller curl får 413. Filen är större än Caddys max_size från steg 5. Höj den där, och SYSTEM_FILEUPLOADLIMIT i steg 4, och starta sedan om båda.

Rätt lösenord ger "Account is locked due to too many failed attempts". Någon, kanske du, har skrivit fel lösenord fler än fem gånger. Starta om Stirling-PDF för att häva låsningen direkt, eller vänta två timmar.

Den första konverteringen av en Word-fil tar omkring 10 sekunder. LibreOffice startar vid behov och stängs efter två minuter utan konvertering. Nästa tar under en sekund.

Frågan om analys visas vid inloggning. Raden SYSTEM_ENABLEANALYTICS=false saknas i containerfilen. Lägg till den, kör systemctl --user daemon-reload och starta om Stirling-PDF.