Kör en Docmost-wiki med Podman utan root

Det här sätter du upp

Docmost är en wiki för ett teams dokumentation, ungefär som Confluence eller Notion: rutiner, introduktion av nyanställda, mötesanteckningar, instruktioner. Sidorna ligger i utrymmen, spaces, som har egna medlemmar, och kan ligga inuti varandra. Flera personer kan redigera samma sida samtidigt och se varandras markörer. Redigeraren har tabeller, kodblock, faktarutor, bifogade filer och tre sorters diagram, och varje sida sparar sin historik.

Docmost utvecklas öppet på GitHub av Docmost, Inc., ett bolag registrerat i Delaware i USA, som också säljer den som molntjänst. Den finns i flera utgåvor:

• Kärnan, som den här guiden sätter upp, är öppen källkod under AGPL 3.0 och gratis.
• Vissa funktioner finns i samma avbild men är låsta tills du lägger till en betald licensnyckel för utgåvan Business eller Enterprise. I version 0.96 gäller det: enkel inloggning (SAML, OpenID Connect, LDAP), tvåfaktorsinloggning, behörigheter på enskilda sidor, API-nycklar, AI-funktionerna och MCP, import från Confluence, Word och PDF, export till Word, sökning i bifogade PDF- och Word-filer, att markera kommentarer som lösta, mallar, personliga utrymmen, att låta läsare kommentera, att stänga av offentlig delning, granskningsloggar, SCIM, verifiering av sidor samt tavlorna Bases och Kanban. Koden för dem ligger under Docmosts egen företagslicens, inte AGPL.

Docmost finns inte på svenska. Varje användare kan välja ett av 12 språk, bland annat engelska, tyska, franska, spanska och nederländska, under Settings > Preferences > Language.

Här körs Docmost som en pod under en egen användare som heter docmost, med PostgreSQL för dess data och Valkey för dess köer, bakom Caddy från Podman-guiden.

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

• Docmost 0.96.0 startade med PostgreSQL 18 och Valkey 9. Arbetsytan och dess ägare skapades via en SSH-tunnel innan Caddy sattes upp, och ett andra försök att skapa en arbetsyta nekades.
• Ingen kunde registrera sig: det enda sättet att komma in var en inbjudan. Inbjudningar och en återställning av lösenord kom fram via e-post, och utan e-post gick inbjudningslänken att kopiera för hand. En avaktiverad medlem loggades ut direkt och kunde inte logga in igen.
• Ett utrymme delades med en medlem som bara fick läsa, och ett annat utrymme var dolt för honom, även i sökningen.
• Två personer redigerade samma sida samtidigt i två webbläsare, och båda såg den andras text och markör medan de skrev. En kommentar från den ena syntes för den andra.
• En sida fick en bild och en PDF, som inte gick att öppna utan inloggning, ett Mermaid-diagram och en Excalidraw-skiss. Sökningen hittade ett ord på en sida. En sidas historik visade två versioner, och den äldre återställdes.
• En Markdown-fil importerades som en sida, och en sida och ett helt utrymme exporterades som Markdown och HTML.
• Inloggningar sparades med besökarens riktiga adress, och en förfalskad X-Forwarded-For-header struntades i. En avlyssning av serverns trafik visade vilka externa tjänster Docmost anropar, i steg 11.
• En uppdatering från Docmost 0.95.0 till 0.96.0, genom att byta tagg, behöll alla sidor. Wikin återställdes från en säkerhetskopia till tomma volymer, och allt startade igen av sig självt efter en omstart av servern, även en ändring som gjordes sekunderna före.

Podden använde omkring 400 MB minne i vila och 520 MB efter en timmes användning, det mesta för Docmost själv.

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 docs.example.com som pekar på din server;
• för inbjudningar och återställning av lösenord via e-post, ett e-postkonto som kan skicka via din e-postleverantörs SMTP-server, till exempel docs@example.com. Docmost fungerar utan, som steg 10 förklarar.

Exemplen använder docs.example.com för wikin, 203.0.113.10 för serverns IPv4-adress, smtp.example.com för leverantörens SMTP-server och anna@example.com för dig. Byt ut dem genomgående.

1. Skapa användaren

Som root:

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

Allt fram till steg 5 körs som docmost.

2. Skapa hemligheterna

openssl rand -hex 32 | tr -d '\n' | podman secret create docmost-app-secret -
DB_PASSWORD=$(openssl rand -hex 24)
printf %s "$DB_PASSWORD" | podman secret create docmost-db-password -
printf %s "postgresql://docmost:$DB_PASSWORD@127.0.0.1:5432/docmost" | podman secret create docmost-db-url -
unset DB_PASSWORD

Den första är Docmosts APP_SECRET, som signerar inloggningar och krypterar hemligheter som Docmost lagrar, till exempel inställningarna för en inloggningstjänst. Steg 12 sparar en kopia. Den andra är databaslösenordet, och den tredje är adressen som Docmost ansluter till databasen med, med samma lösenord i. Docmost läser bara lösenordet som en del av den adressen. Alla tre lagras av Podman, inte i filerna nedan.

3. Definiera podden

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

Skapa docmost.pod:

[Pod]
PodName=docmost
# Only Caddy, on this server, can reach Docmost: the port is not open to the internet.
PublishPort=127.0.0.1:8187:3000

[Install]
WantedBy=default.target

Skapa docmost-db.container:

[Container]
ContainerName=docmost-db
Image=docker.io/library/postgres:18-alpine
Pod=docmost.pod
Volume=docmost-db:/var/lib/postgresql
Environment=POSTGRES_USER=docmost POSTGRES_DB=docmost
Secret=docmost-db-password,type=env,target=POSTGRES_PASSWORD
HealthCmd=pg_isready -U docmost
HealthInterval=10s
Notify=healthy
AutoUpdate=registry

[Service]
Restart=always

Skapa docmost-valkey.container:

[Container]
ContainerName=docmost-valkey
Image=docker.io/valkey/valkey:9-alpine
Pod=docmost.pod
Volume=docmost-valkey:/data
Exec=valkey-server --appendonly yes --maxmemory-policy noeviction
AutoUpdate=registry

[Service]
Restart=always

Och docmost-app.container:

[Unit]
Requires=docmost-db.service docmost-valkey.service
After=docmost-db.service docmost-valkey.service

[Container]
ContainerName=docmost-app
Image=docker.io/docmost/docmost:0.96
Pod=docmost.pod
Volume=docmost-storage:/app/data/storage
Environment=APP_URL=https://docs.example.com
Environment=REDIS_URL=redis://127.0.0.1:6379
Environment=STORAGE_DRIVER=local DISABLE_TELEMETRY=true
Secret=docmost-app-secret,type=env,target=APP_SECRET
Secret=docmost-db-url,type=env,target=DATABASE_URL
# Run Node directly, so it gets the stop signal and saves open pages first.
Environment=NODE_ENV=production
WorkingDir=/app/apps/server
Exec=node dist/main
AutoUpdate=registry

[Service]
Restart=always

Vad inställningarna gör:

• APP_URL är adressen som Docmost sätter i varje länk och e-postmeddelande. Den måste vara den publika https://-adressen.
• Docmosts dokumentation och dess eget exempel använder Redis. Valkey, en fork av Redis under en öppen licens, fungerar i dess ställe: Docmost behöver bara en server som talar Redis-protokollet, och utvecklarna säger själva att Valkey går bra. Den håller Docmosts jobbköer, till exempel e-post som väntar på att skickas och nästa version i varje sidas historik, och skickar ändringar i realtid mellan Docmosts processer. --appendonly yes sparar köerna på disk över en omstart, och noeviction hindrar Valkey från att slänga jobb när minnet tar slut, som i Docmosts egen uppsättning.
• STORAGE_DRIVER=local sparar uppladdade bilder och filer i volymen docmost-storage. Docmost kan i stället spara dem i S3-lagring, till exempel Garage, med STORAGE_DRIVER=s3 och inställningarna AWS_S3_ i dess dokumentation. Vi har inte testat det.
• DISABLE_TELEMETRY=true stoppar en daglig rapport till Docmost, steg 11 har detaljerna.
• De tre sista raderna startar Docmosts server direkt i stället för via avbildens eget startkommando, som inte skickar vidare signalen att stoppa. Docmost sparar en öppen sida omkring 10 sekunder efter den senaste ändringen. Utan de raderna gick en ändring som gjordes precis före en omstart förlorad i våra tester; med dem sparades den.
• Taggen 0.96 följer rättningarna av Docmost 0.96, som AutoUpdate=registry installerar av sig självt. Steg 13 beskriver hur du går till nästa version.

Starta den:

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

Vid första starten laddas avbilder ner som tar omkring 1,25 GB på disken, och sedan sätter Docmost upp sin databas. Den är klar när det här skriver ut {"status":"ok" följt av läget för databasen och Valkey:

curl -s http://127.0.0.1:8187/api/health

4. Skapa arbetsytan

Tills det finns en arbetsyta visar Docmost en sida där den första besökaren får skapa den och bli dess ägare. Gör det innan wikin är ute på nätet, via en SSH-tunnel från din egen dator. Kör det här i en ny terminal på din dator:

ssh -L 8187:127.0.0.1:8187 root@203.0.113.10

Låt den vara öppen och öppna http://localhost:8187 i webbläsaren. Sidan Create workspace frågar efter Workspace Name, Your Name, Your Email och Password. Fyll i dem, välj Create workspace, så är du inloggad som ägare. Stäng sedan tunneln med exit.

Från och med nu skickar sidan besökare vidare till inloggningen, och en begäran om att skapa en till arbetsyta får svaret Workspace setup already completed.

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:

docs.example.com {
    reverse_proxy 127.0.0.1:8187
}

Starta om Caddy med systemctl --user restart caddy, öppna https://docs.example.com och logga in med e-postadressen och lösenordet från steg 4.

Redigering i realtid går över en WebSocket, som Caddy skickar vidare utan någon extra inställning. Caddy skickar också vidare varje besökares adress i headern X-Forwarded-For, och Docmost litar på den. Det är säkert här eftersom bara Caddy når Docmosts port, och Caddy ersätter en sådan header om en besökare skickar den.

6. Bjud in ditt team

Docmost har ingen sida för att registrera sig: man kommer bara in med en inbjudan. Öppna Settings längst ner till vänster, sedan Members och Invite members. Skriv en eller flera e-postadresser, välj en roll och välj Send invitation:

• Member kan arbeta i de utrymmen hen läggs till i.
• Admin kan dessutom bjuda in, skapa utrymmen och ändra alla inställningar för arbetsytan.

Ägaren, du, är administratör och kan dessutom radera arbetsytan.

Varje person får ett e-postmeddelande, "Anna Svensson invited you to Docmost", med en länk till en sida där hen väljer namn och lösenord. Tills e-posten fungerar (steg 10) visar Docmost "Invitation sent" men skickar ingenting: öppna fliken Pending, välj de tre punkterna bredvid personen, sedan Copy link, och skicka länken själv. Den fungerar bara för adressen du bjöd in.

Alla som går med hamnar i gruppen Everyone, som får redigera utrymmet General som skapades med arbetsytan. När någon slutar väljer du de tre punkterna bredvid personen under Members och sedan Deactivate member. Då loggas hen ut direkt, och lösenordet slutar fungera.

Varje sida har en knapp Share, där Share to web publicerar den på internet med en länk som inte kräver inloggning. Alla som får redigera en sida kan göra det, och att stänga av det för hela wikin kräver en betald licens. Är wikin bara för internt bruk, säg det till ditt team.

7. Utrymmen och behörigheter

Ett utrymme är en del av wikin med egna medlemmar, till exempel IT eller Ledning. Bara medlemmarna i ett utrymme ser dess sidor, även i sökningen. Du skapar ett under Settings > Spaces > Create space: ge det ett Space name och en Space slug, det korta namnet i adressen, och välj Create.

För att ge någon åtkomst väljer du utrymmet under Settings > Spaces, sedan fliken Members och Add space members. Välj personer eller grupper och en roll:

• Full access kan dessutom ändra utrymmets inställningar och medlemmar.
• Can edit kan skapa och redigera sidor.
• Can view kan läsa sidor, men inte ändra dem eller kommentera.

Grupper, under Settings > Groups, gör att du slipper lägga till samma personer i varje utrymme. Behörigheter sätts per utrymme: att begränsa en enskild sida till vissa medlemmar kräver en betald licens.

8. Sidor, redigering i realtid och historik

Öppna ett utrymme och välj New page. Första raden är rubriken. Skriv / på en tom rad för listan med block: rubriker, listor, att göra-listor, tabeller, kodblock, faktarutor, Image och File attachment, som laddar upp från din dator, och diagrammen i steg 9. Du kan också klistra in eller dra in bilder. Markdown-genvägar som # och ** fungerar medan du skriver. En sida kan rymma andra sidor, som du skapar med + bredvid den i sidofältet.

Ändringar sparas medan du skriver. När andra öppnar samma sida ser de din markör med ditt namn, och din text medan du skriver den. För att kommentera markerar du lite text och väljer Comment i menyn som dyker upp; kommentarerna syns i panelen som öppnas med pratbubblan uppe till höger, där andra kan svara.

Page history, i sidans meny (de tre punkterna uppe till höger), listar tidigare versioner. Välj en för att se den och Restore för att gå tillbaka till den. En ny version sparas omkring fem minuter efter den senaste ändringen, eller en minut för en sida som fortfarande är ny, så det tar några minuter innan de senaste ändringarna syns där.

Sökrutan Search högst upp söker i rubriker och text i alla utrymmen du kan se.

9. Diagram och bifogade filer

Menyn / har tre sorters diagram:

• Mermaid diagram ritar ett diagram från text, till exempel graph LR följt av rader som Router --> Switch. Det ritas i webbläsaren.
• Excalidraw (Whiteboard) är en whiteboard för skisser, som öppnas när du dubbelklickar på den och sparas som en bild på sidan med Save & Exit. Den är inbyggd i Docmost, men text i en skiss laddar sitt handskriftstypsnitt från esm.sh, en publik tjänst för programpaket.
• Draw.io (diagrams.net) öppnar draw.io-redigeraren från embed.diagrams.net, som drivs av JGraph Ltd i Storbritannien, i användarens webbläsare. Vill du köra redigeraren själv startar du avbilden docker.io/jgraph/drawio och sätter DRAWIO_URL till dess adress. Vi har inte testat det.

Bilder, filer och diagram sparas i volymen docmost-storage, upp till 50 MB styck; FILE_UPLOAD_SIZE_LIMIT=100mb i docmost-app.container höjer gränsen. En besökare som inte är inloggad får ett fel för en fils adress, även om hen känner till den.

10. Import, export och e-post

Import och export

Utrymmets meny, de tre punkterna bredvid Pages i sidofältet, har Import pages. Markdown och HTML importerar enstaka filer, Notion importerar ZIP-filen som Notions egen export ger dig, och Upload file importerar en ZIP-fil med Markdown- och HTML-filer. Word, PDF och Confluence är gråade utan betald licens. Vi har testat Markdown, inte Notion.

Export i sidans meny ger dig sidan som Markdown eller HTML, med undersidor och bifogade filer om du vill. Export space i utrymmets meny exporterar alla sidor i det som en ZIP-fil. Det är en bra kopia att läsa utan Docmost, men ingen säkerhetskopia: användare, behörigheter, kommentarer och historik följer inte med.

E-post

Docmost skickar e-post för inbjudningar, återställning av lösenord och aviseringar om sidor som användare bevakar, omnämnanden och kommentarer. Som standard skickar den ingenting, och utan e-post:

• säger inbjudningar "Invitation sent", men kommer bara fram om du kopierar länken som i steg 6;
• säger Forgot your password? att en länk har skickats, men ingenting kommer fram;
• får ingen aviseringar via e-post.

Konton och inloggning med lösenord fungerar som vanligt.

För att skicka e-post via din e-postleverantör sparar du som docmost kontots lösenord som en hemlighet:

printf %s 'the-smtp-password' | podman secret create docmost-smtp-password -

Lägg till de här raderna i docmost-app.container, med din egen server, ditt konto och din avsändaradress:

Environment=MAIL_DRIVER=smtp SMTP_HOST=smtp.example.com SMTP_PORT=587 SMTP_SECURE=false
Environment=SMTP_USERNAME=docs@example.com MAIL_FROM_ADDRESS=docs@example.com MAIL_FROM_NAME=Docs
Secret=docmost-smtp-password,type=env,target=SMTP_PASSWORD

Och starta om:

systemctl --user daemon-reload
systemctl --user restart docmost-app

Port 587 med SMTP_SECURE=false ansluter utan TLS och byter till STARTTLS så snart servern erbjuder det. För port 465, som använder TLS från början, anger du SMTP_PORT=465 SMTP_SECURE=true. De flesta leverantörer kräver att MAIL_FROM_ADDRESS är samma som kontot. Vi testade e-posten mot en testserver för e-post på samma maskin, inte via en riktig leverantör: inbjudan och återställningen av lösenordet kom fram med länkar till https://docs.example.com.

11. Externa tjänster

Vi avlyssnade serverns DNS-uppslagningar och utgående anslutningar medan Docmost sattes upp och användes. Docmost själv kontaktade en extern tjänst, och har en till som steg 3 stänger av:

• api.github.com, som drivs av GitHub i USA, varje gång någon öppnar inställningarna, för att visa New update bredvid versionsnumret när det finns en nyare version. Den skickar ingenting om wikin. Det finns ingen inställning för att stänga av den.
• tel.docmost.com, Docmosts egen tjänst, en gång om dagen från 24 timmar efter starten, om inte DISABLE_TELEMETRY=true är satt. Rapporten innehåller Docmosts version, antalet användare, sidor, utrymmen och arbetsytor, och ett id som räknas fram från arbetsytans id med din APP_SECRET, så att det inte går att spåra tillbaka. Det har vi läst i Docmosts kod; vårt test pågick inte länge nog för att se en rapport.

I användarnas webbläsare laddas draw.io-redigeraren från embed.diagrams.net och Excalidraws typsnitt från esm.sh, som steg 9 beskriver. Inbäddningar som användare lägger in på sidor, till exempel från YouTube, Loom eller Miro, laddas från de webbplatserna, som på vilken webbsida som helst.

Med en licens behöver enkel inloggning via authentik eller Keycloak på samma server en av lösningarna i steg 8 i Podman-guiden.

12. Säkerhetskopiera

Som docmost:

umask 077
mkdir -p ~/backup
podman exec docmost-db pg_dump -U docmost -d docmost > ~/backup/docmost-db.sql
podman volume export docmost-storage > ~/backup/docmost-storage.tar
podman secret inspect --showsecret --format '{{.SecretData}}' docmost-app-secret > ~/backup/app-secret.txt

Det sparar databasen, med alla sidor, historik, kommentarer, användare och behörigheter; de uppladdade bilderna, filerna och diagrammen; och APP_SECRET från steg 2. Dumpen körs medan Docmost fortsätter att fungera. Valkey behöver ingen säkerhetskopia. Kopiera ~/backup till en annan maskin, till exempel med restic, och förvara den säkert: den innehåller allt ert innehåll och hemligheten.

För att återställa till en tom pod, som docmost, med säkerhetskopian i ~/backup:

systemctl --user stop docmost-pod
podman volume rm docmost-db docmost-storage
podman volume create docmost-storage
podman volume import docmost-storage ~/backup/docmost-storage.tar
systemctl --user start docmost-db
podman exec -i docmost-db psql -q -U docmost -d docmost < ~/backup/docmost-db.sql
systemctl --user start docmost-pod

Genom att bara starta databasen först läses säkerhetskopian in innan Docmost sätter upp en tom databas. På en ny server skapar du APP_SECRET från säkerhetskopian i stället för en ny i steg 2:

tr -d '\n' < ~/backup/app-secret.txt | podman secret create docmost-app-secret -

13. Uppdatera

podman auto-update letar en gång om dagen efter nya avbilder av Docmost, PostgreSQL och Valkey och startar om podden när någon har ändrats. Docmost uppdaterar sin databas när den startar. För att uppdatera direkt:

podman auto-update

Docmost ger ut en ny version, till exempel 0.97, varannan månad ungefär. Alla ser New update bredvid versionsnumret längst ner i inställningarna. Läs versionsinformationen på GitHub, gör en säkerhetskopia, byt sedan taggen i docmost-app.container, till exempel 0.96 mot 0.97, och starta om:

systemctl --user daemon-reload
systemctl --user restart docmost-app

Omstarten laddar först ner den nya avbilden, vilket tar en minut, och Docmost uppdaterar sin databas när den startar.

Felsökning

Sidhuvudet säger "Real-time editor connection lost. Retrying...", och andras ändringar syns inte. WebSocketen till /collab kommer inte fram. Med Caddy-blocket från steg 5 gör den det; en annan proxy framför, till exempel ett CDN, måste också skicka vidare WebSockets.

En inbjudan eller en återställning av lösenord kommer aldrig fram. Kör journalctl --user -u docmost-app | grep -i -E 'mail|smtp' som docmost. En rad med "Error processing send-email job" har e-postserverns svar, eller orsaken till att den inte gick att nå. Finns ingen sådan rad saknas raden med MAIL_DRIVER=smtp, och då slänger Docmost all e-post.

Docmost startar inte, och loggen säger något om APP_SECRET. Hemligheten saknas eller är kortare än 32 tecken. Kontrollera med podman secret ls och skapa den igen som i steg 2.

Det tar 10 sekunder att stoppa eller starta om Docmost. Docmost sparar öppna sidor när den stoppas och väntar sedan, och Podman stoppar den efter 10 sekunder. Det är väntat med inställningarna i steg 3.