BookStack je jednoduchá open-source platforma určená na tvorbu internej dokumentácie, manuálov, postupov a znalostnej databázy.

V tomto návode si ukážeme inštaláciu BookStack pomocou Docker Compose, databázy MariaDB a následné sprístupnenie cez internú doménu s HTTPS certifikátom vystaveným pomocou FreeIPA CA.

Čo budeme potrebovať?

Na inštaláciu budeme potrebovať:

• Linux server s Dockerom a Docker Compose
• približne 2 GB RAM
• niekoľko GB voľného diskového priestoru
• interný DNS záznam
• MariaDB databázu
• SSL certifikát
• funkčný systémový čas / NTP

V tomto návode budeme používať:

bookstack.example.local

a ukážkovú IP adresu:

192.0.2.10

Tieto hodnoty nahraďte vlastnou internou doménou a IP adresou servera.

Vytvorenie pracovného adresára

mkdir -p ~/bookstack
cd ~/bookstack

Vytvorenie APP_KEY

BookStack vyžaduje aplikačný šifrovací kľúč.

Pri použití LinuxServer.io image ho môžeme vygenerovať:

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

Výstup bude vyzerať približne:

base64:xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Tento kľúč si uložíme do súboru .env.

Vytvorenie databázových hesiel

Vygenerujeme náhodné heslá:

DBPASS="$(openssl rand -hex 32)"
ROOTPASS="$(openssl rand -hex 32)"

Vytvoríme:

nano .env

Obsah:

APP_KEY=base64:SEM_VLOZTE_VYGENEROVANY_APP_KEY
BOOKSTACK_DB_PASSWORD=SEM_VLOZTE_DB_HESLO
BOOKSTACK_DB_ROOT_PASSWORD=SEM_VLOZTE_ROOT_DB_HESLO

Po vytvorení súbor zabezpečíme:

chmod 600 .env

Ak používame Git:

echo '.env' >> .gitignore

Súbor .env obsahuje citlivé údaje a nemal by byť publikovaný ani uložený vo verejnom Git repozitári.

Docker Compose

Vytvoríme:

nano docker-compose.yml

a vložíme:

services:
  bookstack:
    image: lscr.io/linuxserver/bookstack:latest
    container_name: bookstack
    restart: unless-stopped

    ports:
      - "192.0.2.10:6875:80"

    environment:
      - PUID=1000
      - PGID=1000
      - TZ=Europe/Bratislava

      - APP_URL=https://bookstack.example.local
      - APP_KEY=${APP_KEY}

      - DB_HOST=bookstack-db
      - DB_PORT=3306
      - DB_USERNAME=bookstack
      - DB_PASSWORD=${BOOKSTACK_DB_PASSWORD}
      - DB_DATABASE=bookstackapp

    depends_on:
      - bookstack-db

    volumes:
      - bookstack_config:/config


  bookstack-db:
    image: lscr.io/linuxserver/mariadb:latest
    container_name: bookstack-db
    restart: unless-stopped

    environment:
      - PUID=1000
      - PGID=1000
      - TZ=Europe/Bratislava

      - MYSQL_ROOT_PASSWORD=${BOOKSTACK_DB_ROOT_PASSWORD}
      - MYSQL_DATABASE=bookstackapp
      - MYSQL_USER=bookstack
      - MYSQL_PASSWORD=${BOOKSTACK_DB_PASSWORD}

    volumes:
      - bookstack_db_config:/config


volumes:
  bookstack_config:
  bookstack_db_config:

Použitím Docker volumes zabezpečíme, že konfigurácia BookStacku a databáza zostanú zachované aj po vytvorení nového kontajnera.

Kontrola konfigurácie

sudo docker compose config >/dev/null && echo "COMPOSE OK"

Správny výsledok:

COMPOSE OK

Stiahnutie Docker images

sudo docker compose pull

Spustenie BookStack

sudo docker compose up -d

Stav kontajnerov:

sudo docker compose ps

Mali by sme vidieť:

bookstack       Up
bookstack-db    Up

Kontrola webovej aplikácie

BookStack môžeme pred konfiguráciou HTTPS otestovať:

curl -sS -o /dev/null -w 'HTTP %{http_code}\n' \
http://192.0.2.10:6875/

Funkčná aplikácia môže odpovedať napríklad:

HTTP 302

Ide o presmerovanie na webové rozhranie alebo prihlasovaciu stránku.

Interný DNS záznam

V internom DNS vytvoríme A záznam:

bookstack.example.local → 192.0.2.10

Ak používame FreeIPA DNS, záznam môžeme vytvoriť priamo v administrácii FreeIPA.

SSL certifikát z FreeIPA

Keďže používame internú .local doménu, verejný Let’s Encrypt certifikát nie je vhodný.

SSL certifikát preto vystavíme pomocou internej FreeIPA CA.

Certifikát by mal obsahovať:

CN  = bookstack.example.local
SAN = DNS:bookstack.example.local

Výsledkom budú napríklad súbory:

bookstack.example.local.key
bookstack.example.local.pem
ca.crt

Klientske zariadenia musia dôverovať FreeIPA CA, aby sa HTTPS stránka zobrazovala bez bezpečnostného upozornenia.

Reverse proxy

Pred BookStack môžeme umiestniť Nginx reverse proxy.

Príklad konfigurácie:

server {
    listen 80;
    server_name bookstack.example.local;

    return 301 https://$host$request_uri;
}

server {
    listen 443 ssl;
    server_name bookstack.example.local;

    ssl_certificate /etc/nginx/ssl/bookstack.example.local.pem;
    ssl_certificate_key /etc/nginx/ssl/bookstack.example.local.key;

    location / {
        proxy_pass http://192.0.2.10:6875;

        proxy_http_version 1.1;

        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto https;
    }
}

Po zmene konfigurácie skontrolujeme syntax:

sudo nginx -t

A následne Nginx reštartujeme:

sudo systemctl restart nginx

Finálny prístup

Po dokončení konfigurácie bude BookStack dostupný na:

https://bookstack.example.local

Prvé prihlásenie je

Meno: admin@admin.com
Heslo: password

V docker-compose.yml musí byť zároveň nastavené:

APP_URL=https://bookstack.example.local

Ak túto hodnotu zmeníme až po prvom spustení, BookStack kontajner znova vytvoríme:

sudo docker compose up -d --force-recreate bookstack

Kontrola kontajnerov

sudo docker compose ps

Log aplikácie:

sudo docker logs --tail 100 bookstack

Pri úspešnom spustení môžeme vidieť napríklad:

INFO  Nothing to migrate.
[ls.io-init] done.

Zálohovanie

Pri zálohovaní BookStack je potrebné uchovávať minimálne:

BookStack /config
MariaDB /config
docker-compose.yml
.env

Súbor .env obsahuje APP_KEY a databázové heslá a musí byť uložený bezpečne.

APP_KEY je obzvlášť dôležitý. Pri obnove existujúcej BookStack inštalácie by mal byť použitý rovnaký APP_KEY ako v pôvodnej inštalácii.