Det här sätter du upp
BookStack är en wiki för ett teams dokumentation: rutiner, anteckningar om servrar, instruktioner, introduktion av nyanställda. Innehållet ordnas som i ett bibliotek, i hyllor, böcker, kapitel och sidor, och du skriver i en redigerare som fungerar som en ordbehandlare, eller i Markdown. Den sparar varje version av en sida, söker i all text och har en granskningslogg över vem som gjorde vad.
BookStack är skapad av Dan Brown, en utvecklare i Storbritannien, och utvecklas öppet tillsammans med användarna på Codeberg, en tjänst för kodlagring som drivs av en ideell förening i Berlin. Den är öppen källkod under MIT-licensen. Betald support säljs av HTTP Functions Ltd, ett bolag registrerat i England. I våra tester letade den inte efter uppdateringar och skickade inga användningsdata. Som standard använder den två externa tjänster: den hämtar en profilbild för varje ny användare från Gravatar, som drivs av Automattic i USA, genom att skicka en hash av användarens e-postadress, och dess diagramredigerare laddas i webbläsaren från diagrams.net, som drivs av draw.io Limited i Storbritannien. Steg 3 stänger av båda.
BookStack ger inte ut någon egen containeravbild; dess dokumentation hänvisar till två som användare har gjort. Den här guiden använder den från LinuxServer.io, en grupp frivilliga som underhåller en stor samling containeravbilder. Det är den första som BookStacks dokumentation listar, versionen vi testade fanns där dagen efter att den släpptes, och den fungerar utan root här. Den andra är solidnerd/bookstack.
Här körs BookStack som en pod under en egen användare som heter bookstack, med MariaDB för dess data, 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:
- BookStack 26.09.1 startade med MariaDB 11.8, och standardkontot
admin@admin.combyttes ut innan Caddy sattes upp. Utifrån misslyckades en inloggning medadmin@admin.comochpassword. - Registrering och offentlig åtkomst var avstängda från början.
- Granskningsloggen visade varje besökares riktiga adress, över IPv4 och IPv6, och struntade i en förfalskad
X-Forwarded-For-header. Tiderna visades i svensk tid. - En hylla, en bok och sidor skapades, med en uppladdad bild och ett kodblock. Sökningen hittade ett ord i en sidas text, och en ändring gav en andra revision. En PDF-export fick med bilden.
- Gränssnittet visades på svenska, både för en användare och som standard för alla.
- Med de externa tjänsterna avstängda visade en avlyssning av serverns trafik inga anslutningar när en användare skapades, och diagramredigeraren var borta.
- Utan e-post misslyckades en inbjudan och en återställning av lösenord, som steg 9 beskriver.
- En uppdatering från BookStack 26.05.5 till 26.09.1 gick igenom med
podman auto-update. Wikin återställdes från en säkerhetskopia till tomma volymer, och allt startade igen av sig självt efter en omstart av servern.
Podden använde omkring 160 MB minne, det mesta för MariaDB.
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.comsom pekar på din server.
Exemplen använder wiki.example.com för wikin och 203.0.113.10 för serverns IPv4-adress, som ip -brief address show eth0 visar. Byt ut dem genomgående.
1. Skapa användaren
Som root:
useradd -m -s /bin/bash bookstack
loginctl enable-linger bookstack
machinectl shell bookstack@
Allt fram till steg 5 körs som bookstack.
2. Skapa hemligheterna
podman run --rm --entrypoint /bin/bash lscr.io/linuxserver/bookstack:latest appkey | tr -d '\n' | podman secret create bookstack-app-key -
openssl rand -hex 24 | tr -d '\n' | podman secret create bookstack-db-password -
Den första raden laddar ner BookStacks avbild och använder dess kommando appkey för att skapa applikationsnyckeln, som BookStack krypterar sessioner och användarnas tvåfaktorshemligheter med. Utan den är en återställd säkerhetskopia till liten nytta, så steg 11 sparar en kopia. Den andra raden skapar databaslösenordet. Båda lagras av Podman, inte i filerna nedan.
3. Definiera podden
mkdir -p ~/.config/containers/systemd
cd ~/.config/containers/systemd
Skapa bookstack.pod:
[Pod]
PodName=bookstack
# Only Caddy, on this server, can reach BookStack: the port is not open to the internet.
PublishPort=127.0.0.1:8104:80
[Install]
WantedBy=default.target
Skapa bookstack-db.container:
[Container]
ContainerName=bookstack-db
Image=docker.io/library/mariadb:11.8
Pod=bookstack.pod
Volume=bookstack-db:/var/lib/mysql
Environment=MARIADB_DATABASE=bookstack MARIADB_USER=bookstack MARIADB_RANDOM_ROOT_PASSWORD=1 MARIADB_AUTO_UPGRADE=1
Secret=bookstack-db-password,type=env,target=MARIADB_PASSWORD
HealthCmd=healthcheck.sh --connect --innodb_initialized
HealthInterval=10s
Notify=healthy
AutoUpdate=registry
[Service]
Restart=always
Och bookstack-app.container:
[Unit]
Requires=bookstack-db.service
After=bookstack-db.service
[Container]
ContainerName=bookstack-app
Image=lscr.io/linuxserver/bookstack:latest
Pod=bookstack.pod
Volume=bookstack-config:/config
Environment=APP_URL=https://wiki.example.com APP_PROXIES=203.0.113.10
Environment=TZ=Europe/Stockholm APP_DISPLAY_TIMEZONE=Europe/Stockholm
Environment=DISABLE_EXTERNAL_SERVICES=true
Environment=DB_HOST=127.0.0.1 DB_PORT=3306 DB_DATABASE=bookstack DB_USERNAME=bookstack
Secret=bookstack-app-key,type=env,target=APP_KEY
Secret=bookstack-db-password,type=env,target=DB_PASSWORD
AutoUpdate=registry
[Service]
Restart=always
Vad inställningarna gör:
APP_URLär adressen som BookStack sätter i varje länk och formulär. Den måste vara den publikahttps://-adressen.APP_PROXIESär adressen som BookStack litar på när den får veta besökarens riktiga adress. Caddys anslutningar kommer in i podden från serverns egen IPv4-adress, som Podman-guiden förklarar, så det är den du anger. Utan den visar granskningsloggen203.0.113.10för alla.APP_DISPLAY_TIMEZONEvisar tider i svensk tid. BookStack lagrar dem fortfarande i UTC, som är dess standard och håller dem rätt när sommartiden börjar och slutar.TZställer in tidszonen för containerns egna loggar.DISABLE_EXTERNAL_SERVICES=truestoppar uppslagningarna mot Gravatar och tar bort diagramredigeraren från draw.io. Steg 10 har detaljerna.- MariaDB ligger kvar på 11.8, en version med långtidsstöd, och
MARIADB_AUTO_UPGRADEuppdaterar dess systemtabeller efter en uppdatering inom den. BookStack följer sina nya versioner och uppdaterar sin databas själv när den startar. - Uppladdade bilder och filer, och containerns inställningar för webbservern, hamnar i volymen
bookstack-config; själva sidorna ligger i databasen.
Starta den:
systemctl --user daemon-reload
systemctl --user start bookstack-pod
systemctl --user enable --now podman-auto-update.timer
Vid första starten laddas omkring 780 MB avbilder ner, och BookStack behöver en minut för att sätta upp sin databas. Den är klar när det här skriver ut 302:
curl -s -o /dev/null -w '%{http_code}\n' http://127.0.0.1:8104/
4. Byt ut standardadministratören
BookStack skapar sitt första konto som admin@admin.com med lösenordet password, och den som känner till det kan logga in så snart wikin är ute på nätet. Byt det innan du lägger till wikin i Caddy. En SSH-tunnel hjälper inte här: BookStack skickar varje länk och formulär till https://wiki.example.com, som inte svarar än. Använd i stället BookStacks eget kommando:
podman exec bookstack-app php /app/www/artisan bookstack:create-admin --initial --email=you@example.com --name="Ditt Namn" --generate-password
--initial ersätter uppgifterna för det första administratörskontot i stället för att lägga till ett nytt. Kommandot skriver ut ett nytt slumpat lösenord och inget annat. Spara det i din lösenordshanterare. Du kan byta det senare under My Account > Access & Security.
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:
wiki.example.com {
reverse_proxy 127.0.0.1:8104
}
Starta om Caddy med systemctl --user restart caddy och öppna https://wiki.example.com. Logga in med din e-postadress och lösenordet från steg 4. Den gamla inloggningen, admin@admin.com med password, får svaret "These credentials do not match our records."
6. Kontrollera vem som kommer in
Under Settings:
- Registration: Enable registration är avstängt, så ingen kan registrera sig.
https://wiki.example.com/registerskickar besökaren tillbaka till inloggningssidan. - Features & Security: Allow public access är avstängt, så varje sida kräver inloggning.
Du skapar konton själv under Settings > Users > Add New User. Tills e-posten fungerar (steg 9) stänger du av Send user invite email och sätter ett lösenord åt användaren.
Uppladdade bilder är undantaget från inloggningen: den som har en bilds exakta adress kan öppna den utan att logga in. BookStack gör så av prestandaskäl och skriver det bredvid Enable higher security image uploads under Features & Security, som lägger till en slumpad sträng i namnen på nya uppladdningar. Tänk på det innan du laddar upp skärmdumpar som visar lösenord eller kunddata.
BookStack kan också lämna inloggningen till en tjänst för enkel inloggning, till exempel authentik, via OpenID Connect eller SAML 2.0, eller till LDAP. Det ställs in med AUTH_METHOD och de tillhörande inställningarna i BookStacks dokumentation. Vi har inte testat det här.
7. Hyllor, böcker och sidor
Innehållet ordnas i fyra nivåer: hyllor rymmer böcker, böcker rymmer kapitel och sidor. Så här kommer du igång:
- Books > Create New Book, ge den ett namn, till exempel
Servrar, och välj Save Book. - Shelves > New Shelf, ge den ett namn, till exempel
IT, lägg till boken med + bredvid den under Add books to this shelf, och välj Save Shelf. - Öppna boken och välj New Page. Redigeraren sparar utkast medan du skriver.
I redigeraren öppnar Insert image bildhanteraren, där Upload Image lägger till en bild från din dator; markera den och välj Select Image för att sätta in den på sidan. Knappen More sist i verktygsfältet har Insert code block, som öppnar en kodredigerare med en lista över språk. Save Page publicerar sidan.
Varje sparning blir en ny revision. Set Changelog bredvid Save Page lägger till en kommentar till den, och Revisions på sidan listar varje version, med Changes för att jämföra och Restore för att gå tillbaka. BookStack behåller som standard de senaste 100 revisionerna av varje sida.
Sökrutan högst upp söker i texten på varje sida, bok och hylla som du har behörighet att se. Export på en sida eller en bok ger dig en PDF, en webbsida, Markdown, ren text eller en ZIP-fil. Vill du skriva i Markdown i stället finns Switch to Markdown Editor i menyn bredvid Editing Draft i redigeraren.
8. Använd BookStack på svenska
BookStack är översatt till svenska. Varje användare väljer Svenska under My Account > Profile Details > Preferred Language, och du kan ställa in det när du skapar användaren.
För att göra svenska till standard för alla som inte har valt något språk lägger du som bookstack till den här raden i bookstack-app.container och startar om:
Environment=APP_LANG=sv
systemctl --user daemon-reload
systemctl --user restart bookstack-app
9. E-post
BookStack skickar e-post för inbjudningar, återställning av lösenord, bekräftelse av e-postadressen vid registrering och aviseringar om sidor som användare följer. Den här guiden sätter inte upp e-post, och utan den:
- misslyckas det att skapa en användare med Send user invite email påslaget, med "Could not create user since invite email failed to send";
- visar Forgot Password? på inloggningssidan "An unknown error occurred" för en adress som har ett konto;
- visar Settings > Maintenance > Send a Test Email felet
Connection could not be established with host "localhost:587".
Konton och inloggning med lösenord fungerar som vanligt.
För att skicka e-post pekar du BookStack mot en SMTP-server, till exempel den från guiden om mailserver eller din e-postleverantörs. Som bookstack sparar du SMTP-lösenordet som en hemlighet:
printf %s 'the-smtp-password' | podman secret create bookstack-mail-password -
Lägg sedan till de här raderna i bookstack-app.container, med din egen server, ditt konto och din avsändaradress:
Environment=MAIL_DRIVER=smtp MAIL_HOST=mail.example.com MAIL_PORT=587 MAIL_ENCRYPTION=tls
Environment=MAIL_USERNAME=wiki@example.com MAIL_FROM=wiki@example.com MAIL_FROM_NAME=Wiki
Secret=bookstack-mail-password,type=env,target=MAIL_PASSWORD
Starta om som i steg 8 och kontrollera med Send a Test Email. Port 587 med MAIL_ENCRYPTION=tls använder STARTTLS; för port 465, som använder TLS från början, byter du port. Vi har inte testat att skicka, eftersom den här servern saknar mailserver.
10. Externa tjänster
Med DISABLE_EXTERNAL_SERVICES=true från steg 3 gör servern inga externa anslutningar vid normal användning. Vi kontrollerade det genom att avlyssna dess DNS-uppslagningar och utgående anslutningar medan BookStack startade, medan en sida exporterades och medan användare skapades. Utan den raden ändras två saker:
- När en användare skapas hämtar servern en bild från
www.gravatar.comoch skickar då en MD5-hash av användarens e-postadress. I vår avlyssning gav varje ny användare en uppslagning avwww.gravatar.comoch en anslutning dit. - Sidredigeraren får en knapp för diagram, och när en användare öppnar den laddar webbläsaren draw.io-redigeraren från
embed.diagrams.net.
För att behålla diagrammen utan diagrams.net kör du webbappen draw.io själv och pekar BookStack mot den, efter DISABLE_EXTERNAL_SERVICES=true:
Environment=DRAWIO=https://draw.example.com/?embed=1&proto=json&spin=1&configure=1
Webbappen draw.io har en egen avbild, docker.io/jgraph/drawio. Vi har inte testat den lösningen.
Länkar och inbäddade videor som användare lägger in på sidor, till exempel från YouTube, laddas från de webbplatserna i läsarens webbläsare, som på vilken webbsida som helst. Webhooks, under Settings > Webhooks, anropar de adresser du anger.
11. Säkerhetskopiera
Som bookstack:
umask 077
mkdir -p ~/backup
podman exec bookstack-db sh -c 'mariadb-dump -ubookstack -p"$MARIADB_PASSWORD" --single-transaction bookstack' > ~/backup/bookstack-db.sql
podman volume export bookstack-config --output ~/backup/bookstack-config.tar
podman secret inspect --showsecret --format '{{.SecretData}}' bookstack-app-key > ~/backup/app-key.txt
Det är vad BookStacks egna råd om säkerhetskopiering kräver: databasen, de uppladdade bilderna och filerna, och applikationsnyckeln. Sidor, användare, revisioner och inställningar ligger i databasen, och bilder och bilagor i volymen. Dumpen körs medan BookStack fortsätter att fungera. Kopiera ~/backup till en annan maskin, till exempel med restic, och förvara den säkert: den innehåller allt ert innehåll och applikationsnyckeln.
För att återställa till en tom pod, som bookstack, med säkerhetskopian i ~/backup:
systemctl --user stop bookstack-pod
podman volume rm bookstack-db bookstack-config
podman volume create bookstack-config
podman volume import bookstack-config ~/backup/bookstack-config.tar
systemctl --user start bookstack-db
podman exec -i bookstack-db sh -c 'mariadb -ubookstack -p"$MARIADB_PASSWORD" bookstack' < ~/backup/bookstack-db.sql
systemctl --user start bookstack-app
Genom att bara starta databasen först läses säkerhetskopian in innan BookStack sätter upp en tom databas. På en ny server skapar du nyckeln från säkerhetskopian i stället för en ny i steg 2:
tr -d '\n' < ~/backup/app-key.txt | podman secret create bookstack-app-key -
12. Uppdatera
podman auto-update letar en gång om dagen efter nya avbilder av BookStack och MariaDB och startar om podden när någon har ändrats. BookStack uppdaterar sin databas när den startar. För att uppdatera direkt:
podman auto-update
LinuxServer.io skriver att de inte stöder automatiska uppdateringar. Vill du hellre uppdatera för hand byter du latest i bookstack-app.container mot en versionstagg, till exempel v26.09.1-ls287 från avbildens lista över taggar, tar bort raden AutoUpdate=registry och byter tagg när du vill uppdatera. Håll i båda fallen dina säkerhetskopior aktuella, och läs versionsinformationen på BookStacks blogg före större uppdateringar.
Felsökning
Varje rad i granskningsloggen har serverns egen adress. APP_PROXIES saknas eller anger fel adress. Den måste vara serverns IPv4-adress, inte 127.0.0.1. Rätta den i bookstack-app.container, kör sedan daemon-reload och starta om bookstack-app.
"Could not create user since invite email failed to send". E-post är inte uppsatt. Stäng av Send user invite email och sätt ett lösenord, eller sätt upp e-post som i steg 9.
"An unknown error occurred" efter Forgot Password?. Samma orsak: BookStack kunde inte skicka e-postmeddelandet för återställningen. Settings > Maintenance > Send a Test Email visar felet.