Installera BookStack

Vad BookStack är

Ett program för dokumentation som är byggt som ett bokhyllsystem. Överst ligger hyllor, i dem böcker, i böckerna kapitel, och i kapitlen sidor. Strukturen är bestämd i förväg, och det är själva idén.

De flesta wikiprogram låter er skapa sidor hur som helst, och efter tre månader har ingen längre en aning om var någonting ligger. BookStack tvingar fram ett beslut redan när sidan skapas: vilken bok hör det här hemma i? Det känns styltigt första veckan och räddar er i mars.

Ett företag använder det till rutinerna. En bok för produktionen, en för försäljningen, en för allt som rör ekonomin. Sökfunktionen letar i texten, och varje sida har en historik så att ni kan se vad som ändrades och av vem.

Det här är ett serverprogram

BookStack behöver en webbserver och en databas. Docker ger er båda i en fil. Har ni inte Docker, börja med Installera Docker.

Programmet självt är gratis och öppen källkod. Vill ni slippa driften finns företag som kör BookStack åt er mot betalning, och projektet listar dem på bookstackapp.com.

Windows och Linux Mint

Samma fil på båda. Skapa en mapp som heter bookstack i hemmappen, alltså i C:\Users\ert-namn på Windows och i /home/ert-namn på Linux Mint. Lägg en textfil i mappen som heter compose.yaml:

services:
  bookstack:
    image: lscr.io/linuxserver/bookstack:latest
    environment:
      - PUID=1000
      - PGID=1000
      - TZ=Europe/Stockholm
      - APP_URL=http://localhost:6875
      - APP_KEY=BYT_UT_MIG_NYCKEL
      - DB_HOST=bookstack_db
      - DB_PORT=3306
      - DB_USERNAME=bookstack
      - DB_PASSWORD=BYT_UT_MIG_1
      - DB_DATABASE=bookstackapp
    volumes:
      - ./config:/config
    ports:
      - "6875:80"
    depends_on:
      - bookstack_db
    restart: unless-stopped

  bookstack_db:
    image: mariadb:11
    environment:
      - MARIADB_ROOT_PASSWORD=BYT_UT_MIG_2
      - MARIADB_DATABASE=bookstackapp
      - MARIADB_USER=bookstack
      - MARIADB_PASSWORD=BYT_UT_MIG_1
    volumes:
      - db:/var/lib/mysql
    restart: unless-stopped

volumes:
  db:

Tre saker ska bytas ut. De två raderna som heter BYT_UT_MIG_1 är databasens lösenord och måste vara identiska. BYT_UT_MIG_2 är ett annat lösenord som bara databasen använder internt. Spara båda där företaget sparar lösenord.

APP_KEY är speciell och kan inte vara vilken sträng som helst. Den ska se ut som ordet base64: följt av exakt 44 tecken. På Linux Mint skapar ni en med kommandot nedan, och resultatet klistrar ni in i filen. Vi körde det, och det ger rätt format:

echo "base64:$(openssl rand -base64 32)"

På Windows finns inte openssl som standard, och Docker Desktops interna Linux-distribution är bara till för att köra Docker självt, inte ett skal ni kan öppna och skriva kommandon i. Kör i stället avbildens eget hjälpkommando i PowerShell, det kräver bara Docker:

docker run -it --rm --entrypoint /bin/bash lscr.io/linuxserver/bookstack:latest appkey

Det skriver ut en färdig APP_KEY i samma format, som ni klistrar in i filen.

Öppna terminalen och gå in i mappen. På Windows är det PowerShell:

cd $HOME\bookstack

På Linux Mint heter programmet Terminal:

cd ~/bookstack

Starta sedan:

docker compose up -d

Kommer svaret att ingen compose.yaml hittades står ni i fel mapp. Vänta annars en till två minuter medan databasen sätts upp och öppna http://localhost:6875. Standardinloggningen är admin@admin.com med lösenordet password. Vi körde precis den här filen, och versionen som startade var BookStack v26.05.5.

localhost är alltid den egna datorn. Wikin syns därför bara på maskinen den körs på, och skickar ni adressen till någon i företaget hamnar den personen på sin egen dator. För att bygga strukturen och skriva de första sidorna räcker det. Ska företaget läsa samma böcker behöver BookStack ligga på en maskin som står på, och APP_URL ska då peka på den maskinens adress.

Tre saker att göra först

1. Byt lösenordet på administratörskontot innan ni gör något annat. password står i varenda guide på nätet, inklusive den här.
2. Ändra visningsspråket till svenska under kontoinställningarna (hette Edit Profile i äldre versioner, ligger numera under My Account). Det påverkar bara gränssnittet, inte innehållet, och gör BookStack betydligt mindre skrämmande för den i företaget som hellre slipper engelska.
3. Skapa en bok och skriv en riktig sida i den samma kväll. Strukturen är lätt att älska i teorin och värdelös utan text.

Den vanligaste fällan

Att tappa bort APP_KEY. BookStack krypterar vissa uppgifter med den nyckeln, bland annat inställningar som rör inloggning mot andra tjänster. Startar ni om med en ny nyckel går de uppgifterna inte att läsa längre, och felmeddelandet talar sällan om att det är nyckelns fel.

Spara därför nyckeln tillsammans med lösenorden i samma sekund som ni skapar den. Gör ni en säkerhetskopia av mappen config och databasen men glömmer nyckeln, har ni en kopia som inte går att återställa fullt ut.

Den andra vanliga missen är att sidan laddar men ser sönderslagen ut, utan bilder och formatering. Då pekar APP_URL på fel adress. Skriv in exakt den adress ni skriver i webbläsaren, inklusive portnumret, och kör docker compose up -d igen. Har ni redan hunnit skapa sidor kan gamla länkar i texten peka fel, och då finns ett inbyggt kommando som skriver om dem:

docker compose exec bookstack php /app/www/artisan bookstack:update-url http://gamla-adressen http://nya-adressen