Kör en Outline-wiki för teamet med Podman utan root

Det här sätter du upp

Outline är en wiki och kunskapsbank för ett team: rutiner, introduktion av nyanställda, mötesanteckningar, instruktioner. Dokumenten ligger i samlingar, var och en med sin egen behörighet, och kan läggas inuti varandra. Flera personer kan redigera samma dokument samtidigt och se varandras markörer. Redigeraren fungerar som en modern anteckningsapp, med kortkommandon från Markdown, tabeller, kodblock och bilder, och varje ändring sparas i dokumentets historik.

Outline utvecklas öppet på GitHub av General Outline, Inc., ett bolag i USA, som också säljer den som en tjänst på nätet. Koden är under Business Source License 1.1: du får köra den för din egen organisation, men inte sälja den till andra som en dokumenttjänst. Varje version blir öppen källkod under Apache 2.0-licensen fyra år efter att den släpps. Utgåvan som du kör själv gratis saknar en del funktioner från Outlines betalplaner: inloggning med SAML, gästanvändare, granskningsloggen, import från Confluence och export till PDF. Som standard rapporterar servern antalet användare, arbetsytor, samlingar och dokument till Outlines uppdateringstjänst en gång om dagen; steg 3 stänger av det.

Outline har inga lösenord. Man loggar in via en inloggningstjänst: Google, Microsoft, Slack, en OpenID Connect-server som authentik, eller en länk som skickas med e-post. Den här guiden använder e-postlänken, tillsammans med passkeys. För ett litet företag är det enklast: det kräver ingen extra tjänst att köra och hålla uppdaterad, bara det e-postkonto ni redan har, och var och en loggar in med sin jobbadress. Efter första inloggningen lägger var och en till en passkey, så att den dagliga inloggningen inte behöver vänta på ett mejl. Kör ni redan authentik för era andra appar är det bättre att koppla Outline dit, eftersom du då stänger av en avgående medarbetares åtkomst på ett enda ställe. Körs authentik på samma server når Outline den bara med en av lösningarna i steg 8 i Podman-guiden.

Här körs Outline som en pod under en egen användare som heter outline, 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:

• Outline 1.11.0 startade med PostgreSQL 18 och Valkey 9. Arbetsytan och dess administratör skapades från servern innan Caddy sattes upp, och ett andra försök att skapa en arbetsyta nekades.
• Administratören och en inbjuden användare loggade in med e-postlänken, och inbjudan kom fram med e-post. Administratören loggade sedan in med en passkey med e-posten avstängd.
• En privat samling och en delad skapades. Den inbjudna användaren såg bara den delade och hittade inte de privata dokumenten genom att söka.
• Ett dokument fick text, en uppladdad bild på 5,7 MB och en andra version i historiken. Sökningen hittade ord i texten. Bilden gick inte att öppna utan att logga in.
• En inloggning med en adress som inte var inbjuden gav inget mejl. En avstängd användare loggades ut direkt och kunde inte få någon ny inloggningslänk.
• Gränssnittet visades på svenska, både för en användare och som standard för nya användare.
• Inloggningsförfrågningar loggades med besökarens riktiga adress, över IPv4 och IPv6, och en förfalskad X-Forwarded-For-header struntades i. En avlyssning av serverns trafik visade inga rapporter till Outlines uppdateringstjänst.
• En uppdatering från Outline 1.10.1 till 1.11.0, genom att byta tagg, behöll alla dokument. 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 precis innan.

Podden använde omkring 300 MB minne, det mesta för Outline 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 wiki.example.com som pekar på din server;
• ett e-postkonto som kan skicka via din e-postleverantörs SMTP-server, till exempel wiki@example.com, med serverns namn och lösenordet. Utan det kan ingen logga in.

Exemplen använder wiki.example.com för wikin, smtp.example.com för leverantörens SMTP-server, wiki@example.com för kontot som skickar e-posten och anna@example.com för dig. Byt ut dem genomgående.

1. Skapa användaren

Som root:

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

Allt fram till steg 5 körs som outline.

2. Skapa hemligheterna

openssl rand -hex 32 | tr -d '\n' | podman secret create outline-secret-key -
openssl rand -hex 32 | tr -d '\n' | podman secret create outline-utils-secret -
openssl rand -hex 24 | tr -d '\n' | podman secret create outline-db-password -
printf %s 'the-smtp-password' | podman secret create outline-smtp-password -

Den första är Outlines hemliga nyckel, som signerar inloggningssessioner och krypterar hemligheterna för integrationer du lägger till. Den andra signerar Outlines interna underhållsanrop. Den tredje är databaslösenordet, och den sista är lösenordet till ditt e-postkonto, i stället för the-smtp-password. Alla fyra lagras av Podman, inte i filerna nedan.

3. Definiera podden

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

Skapa outline.pod:

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

[Install]
WantedBy=default.target

Skapa outline-db.container:

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

[Service]
Restart=always

Skapa outline-valkey.container:

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

[Service]
Restart=always

Och outline-app.container:

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

[Container]
ContainerName=outline-app
Image=docker.io/outlinewiki/outline:1.11
Pod=outline.pod
Volume=outline-data:/var/lib/outline/data
Environment=URL=https://wiki.example.com PORT=3000
Environment=DATABASE_HOST=127.0.0.1 DATABASE_NAME=outline DATABASE_USER=outline PGSSLMODE=disable
Environment=REDIS_URL=redis://127.0.0.1:6379
Environment=FILE_STORAGE=local FILE_STORAGE_UPLOAD_MAX_SIZE=26214400
Environment=TELEMETRY=false
Environment=SMTP_HOST=smtp.example.com SMTP_PORT=587 SMTP_SECURE=false
Environment=SMTP_USERNAME=wiki@example.com SMTP_FROM_EMAIL=wiki@example.com
Secret=outline-secret-key,type=env,target=SECRET_KEY
Secret=outline-utils-secret,type=env,target=UTILS_SECRET
Secret=outline-db-password,type=env,target=DATABASE_PASSWORD
Secret=outline-smtp-password,type=env,target=SMTP_PASSWORD
AutoUpdate=registry

[Service]
Restart=always

Vad inställningarna gör:

• URL är adressen som Outline sätter i varje länk och mejl. Den måste vara den publika https://-adressen.
• Raderna med DATABASE_ pekar Outline mot PostgreSQL i samma pod, och PGSSLMODE=disable låter den ansluta utan TLS, eftersom trafiken stannar i podden.
• Valkey, en fork av Redis, håller Outlines jobbköer. Dess volym behåller jobb som väntar, som att spara en ny version av ett dokument, när podden startas om. Den behöver ingen säkerhetskopia.
• FILE_STORAGE=local lägger uppladdade bilder och filer i volymen outline-data i stället för i S3-lagring. Outlines egen gräns för en uppladdning är 1 MB; 26214400 höjer den till 25 MB.
• TELEMETRY=false stoppar den dagliga rapporten till Outlines uppdateringstjänst.
• Raderna med SMTP_ gäller din e-postleverantör; steg 7 har detaljerna.
• Taggen 1.11 följer felrättningarna av Outline 1.11, som AutoUpdate=registry installerar av sig själv. Steg 12 tar upp hur du går vidare till nästa version.

Starta den:

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

Vid första starten laddas avbilder ner som tar omkring 1,5 GB på disken, och Outline behöver en minut eller två för att sätta upp sin databas. Den är klar när det här skriver ut 301, en omdirigering till HTTPS:

curl -s -o /dev/null -w '%{http_code}\n' http://127.0.0.1:8115/

4. Skapa arbetsytan

Så länge det inte finns någon arbetsyta låter Outline den första besökaren skapa den, med sig själv som administratör. Gör det från servern, innan wikin är ute på nätet, med arbetsytans namn, ditt namn och din e-postadress:

curl -s -X POST http://127.0.0.1:8115/api/installation.create \
  -H 'X-Forwarded-Proto: https' -H 'Content-Type: application/json' \
  -d '{"teamName": "Example", "userName": "Anna Svensson", "userEmail": "anna@example.com"}'

Den skriver ut Redirecting to https://wiki.example.com/home. Kör du den igen svarar den Installation already has existing teams: från och med nu kan ingen skapa någon mer.

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:

wiki.example.com {
    reverse_proxy 127.0.0.1:8115
}

Starta om Caddy med systemctl --user restart caddy och öppna https://wiki.example.com. Sidan säger Log in to Example. Välj Continue with Email, ange din adress och välj Sign In. Ett mejl med ämnet "Magic Sign-in Link" kommer inom en minut, och länken i det loggar in dig.

Caddy skickar vidare varje besökares adress i headern X-Forwarded-For, och Outline litar på den. Det är säkert här, eftersom bara Caddy når Outlines port, och Caddy ersätter en sådan header om en besökare skickar med den.

6. Lägg till en passkey

Med en passkey loggar du in med mobilen, datorns fingeravtrycksläsare eller en säkerhetsnyckel, utan att vänta på ett mejl. Öppna menyn under ditt namn längst ner till vänster och välj Preferences. Då öppnas Outlines inställningar, med dina egna till vänster under Account och, för administratörer, arbetsytans under Workspace. Välj Passkeys och sedan Add Passkey…. Webbläsaren frågar var den ska sparas. Från och med då har inloggningssidan även Continue with Passkey.

Be alla lägga till en efter sin första inloggning. En passkey fungerar på enheten eller i lösenordshanteraren där den sparades; på en ny enhet loggar man in med e-post igen och lägger till en till.

7. E-post

Outline skickar e-post för inloggningslänkar, inbjudningar, aviseringar om dokument som användare följer, länkar till färdiga exporter och ett meddelande till administratörer när någon går med. Utan e-post saknar inloggningssidan Continue with Email: de som har lagt till en passkey kan fortfarande logga in, men ingen annan, och ingen ny användare kan logga in för första gången.

Raderna med SMTP_ i steg 3 skickar via din e-postleverantör på port 587 med STARTTLS, vilket SMTP_SECURE=false ber om: Outline ansluter utan TLS och uppgraderar anslutningen 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. SMTP_FROM_EMAIL är avsändaren mottagarna ser, och de flesta leverantörer kräver att den är samma som kontot.

För att ändra en inställning senare redigerar du outline-app.container som outline och startar om:

systemctl --user daemon-reload
systemctl --user restart outline-app

För att byta lösenord tar du bort hemligheten med podman secret rm outline-smtp-password, skapar den igen som i steg 2 och startar om på samma sätt. Om ett inloggningsmejl inte kommer fram, se Felsökning. Vi testade mejlen med en testserver för e-post på samma maskin, inte via en riktig leverantör.

8. Bjud in ditt team

Välj Invite people… längst ner till vänster, ange varje persons e-postadress och namn, välj roll och välj Send Invites:

• Editor kan skapa, redigera och ta bort dokument.
• Viewer kan läsa och kommentera.
• Admin kan dessutom ändra alla inställningar för arbetsytan.

Var och en får ett mejl, "Anna Svensson invited you to join Example's workspace", med en länk till wikin, där de loggar in med Continue with Email. Bara inbjudna adresser kan logga in: till andra adresser skickar Outline inget mejl. Allowed domains under Authentication i inställningarna ändrar inte det, eftersom den bara gäller inloggningstjänster som Google eller OpenID Connect.

När någon slutar öppnar du Users i inställningarna, väljer User options (de tre punkterna) bredvid personen, sedan Suspend user… och Confirm. Det loggar ut personen direkt och stoppar nya inloggningslänkar, även om personen fortfarande kommer åt sin e-post.

Kontrollera två inställningar under Security i inställningarna innan du bjuder in någon:

• Public document sharing är påslaget, så varje medlem kan publicera ett dokument på internet med en länk som inte kräver inloggning. Stäng av det om wikin bara är för internt bruk.
• Allow users to send invites är påslaget, så även redaktörer kan bjuda in folk.

9. Samlingar och dokument

Dokumenten ligger i samlingar, till exempel Handbok eller Servrar. För att skapa en väljer du New collection i sidofältet, ger den ett namn och ställer in Permission:

• No access gör den privat: bara du, och de personer och grupper du lägger till senare med Share på samlingen, kan se den.
• View only eller Can edit öppnar den för alla i arbetsytan.

Välj sedan New doc uppe till höger. Första raden är rubriken. Skriv / på en tom rad för listan över block: rubriker, listor, tabeller, kodblock och Image, som laddar upp en bild från din dator. Du kan också klistra in eller dra in bilder. Kortkommandon från Markdown som # och ** fungerar medan du skriver. Ett dokument kan innehålla andra dokument, som du skapar med New document i dess meny, de tre punkterna uppe till höger.

Ändringar sparas medan du skriver, och andra som har dokumentet öppet ser dem direkt. History i samma meny listar tidigare versioner, med vad som ändrats. En ny version sparas när alla har stängt dokumentet, eller fem minuter efter den senaste ändringen.

Sökrutan högst upp söker i rubriker och text i alla samlingar du kan se. Ett dokuments text blir sökbar i samma stund som en version sparas, så ett ord du just har skrivit kan ta upp till fem minuter att dyka upp. Export i menyn ger dig dokumentet som Markdown eller HTML. PDF finns inte: i vårt test svarade Outline PDF export is not available in the community edition.

Uppladdade bilder och filer kräver inloggning: en besökare som har adressen till en bild får ett fel. Alla i arbetsytan som har adressen till en bild kan öppna den, även om den ligger i en privat samling, men adresserna är långa och slumpade.

10. Använd Outline på svenska

Outline är översatt till svenska. Varje användare väljer Svenska (Swedish) under Language i Preferences.

För att göra svenska till språket för nya användare lägger du som outline till den här raden i outline-app.container och startar om som i steg 7:

Environment=DEFAULT_LANGUAGE=sv_SE

De som redan har loggat in behåller sitt språk. Inloggningssidan följer språket i besökarens webbläsare.

11. Säkerhetskopiera

Som outline:

umask 077
mkdir -p ~/backup
podman exec outline-db pg_dump -U outline -d outline > ~/backup/outline-db.sql
podman volume export outline-data > ~/backup/outline-data.tar
for s in outline-secret-key outline-utils-secret; do podman secret inspect --showsecret --format '{{.SecretData}}' $s > ~/backup/$s.txt; done

Säkerhetskopian innehåller databasen, med alla dokument, historik, användare och inställningar; de uppladdade bilderna och filerna; och de två nycklarna från steg 2. Dumpen körs medan Outline fortsätter att fungera. umask 077 gör att bara outline kan läsa nya filer; podman volume export --output skulle strunta i den, och därför använder raden >. Kopiera ~/backup till en annan maskin, till exempel med restic, och förvara den säkert: den innehåller allt ert innehåll och nycklarna.

Export data… under Export i inställningarna exporterar också varje samling som Markdown eller HTML i en ZIP-fil och mejlar dig en länk när den är klar. Det är en bra kopia att läsa utan Outline, men ingen fullständig säkerhetskopia: användare, behörigheter och historik följer inte med.

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

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

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

for s in outline-secret-key outline-utils-secret; do tr -d '\n' < ~/backup/$s.txt | podman secret create $s -; done

12. Uppdatera

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

podman auto-update

Outline ger ut en ny version, till exempel 1.12, med en eller två månaders mellanrum. Läs versionsinformationen på GitHub, gör en säkerhetskopia, byt sedan taggen i outline-app.container, till exempel 1.11 mot 1.12, och starta om:

systemctl --user daemon-reload
systemctl --user restart outline-app

Outline uppdaterar sin databas när den startar. Administratörer ser den installerade versionen, och om det finns en nyare, under Installation i inställningarna. För att visa det slår Outline upp den senaste versionen på Docker Hub när sidan öppnas.

Felsökning

Inloggningssidan saknar Continue with Email. Raderna med SMTP_ saknas i outline-app.container, och Outline erbjuder bara inloggning med e-post när den kan skicka e-post. Lägg till dem som i steg 3 och starta om.

Inloggningsmejlet kommer aldrig fram. Kör journalctl --user -u outline-app | grep -i mail som outline. En rad med "Error sending email" innehåller e-postserverns svar, eller orsaken till att den inte gick att nå. Gäller svaret inloggningen kontrollerar du kontot och lösenordshemligheten; tar anslutningen för lång tid kan din leverantör vilja ha den andra porten, 587 eller 465.

"Rate limit exceeded" när du ber om ett inloggningsmejl. Outline tar emot tio förfrågningar om inloggningsmejl i timmen från varje adress. Gränsen ligger i Outlines kod, och RATE_LIMITER_REQUESTS ändrar den inte. Vänta upp till en timme och försök igen. Alla bakom samma kontorsadress delar på de tio.

Sidan förblir tom, eller laddas bara till hälften, efter många omladdningar. Outline tillåter 1000 anrop i minuten från en adress, och ett första besök utan cache laddar några hundra filer. Vänta en minut. Delar ett helt kontor på en adress och slår i gränsen höjer du den med Environment=RATE_LIMITER_REQUESTS=3000.

En uppladdning misslyckas. Filen kan vara större än FILE_STORAGE_UPLOAD_MAX_SIZE, i byte. Höj värdet i outline-app.container och starta om.