bookstack

Bookstack in docker

guide-by-example

Purpose & Overview

Documentation and notes.

• Official site
• Github
• DockerHub

BookStack is a modern, open source, good looking wiki platform for storing and organizing information.

Written in PHP, using Laravel framework, with MySQL database for the user data.
There is no official Dockerhub image so the one maintained by linuxserver.io is used, which uses nginx as a web server.

Files and directory structure

/home/
└── ~/
    └── docker/
        └── bookstack/
            ├── 🗁 bookstack_data/
            ├── 🗁 bookstack_db_data/
            ├── 🗋 .env
            ├── 🗋 docker-compose.yml
            └── 🗋 bookstack-backup-script.sh

• bookstack_data/ - a directory with bookstacks web app data
• bookstack_db_data/ - a directory with database data
• .env - a file containing environment variables for docker compose
• docker-compose.yml - a docker compose file, telling docker how to run the containers
• bookstack-backup-script.sh - a backup script, to be run daily

Only the files are required. The directories are created on the first run.

docker-compose

Dockerhub linuxserver/bookstack example compose.

docker-compose.yml

services:

  bookstack-db:
    image: linuxserver/mariadb
    container_name: bookstack-db
    hostname: bookstack-db
    restart: unless-stopped
    env_file: .env
    volumes:
      - ./bookstack_db_data:/config
    ports:
      - "3306:3306"

  bookstack:
    image: linuxserver/bookstack
    container_name: bookstack
    hostname: bookstack
    restart: unless-stopped
    env_file: .env
    depends_on:
      - bookstack-db
    volumes:
      - ./bookstack_data:/config
    ports:
      - "80:80"

networks:
  default:
    name: $DOCKER_MY_NETWORK
    external: true

.env

# GENERAL
DOCKER_MY_NETWORK=caddy_net
TZ=Europe/Bratislava

#LINUXSERVER.IO
PUID=1000
PGID=1000

# BOOKSTACK-MARIADB
MYSQL_ROOT_PASSWORD=bookstack
MYSQL_DATABASE=bookstack
MYSQL_USER=bookstack
MYSQL_PASSWORD=bookstack

# BOOKSTACK
APP_URL=https://book.example.com
DB_HOST=bookstack-db
DB_USER=bookstack
DB_PASS=bookstack
DB_DATABASE=bookstack

# USING SENDINBLUE FOR SENDING EMAILS
MAIL_DRIVER=smtp
MAIL_ENCRYPTION=tls
MAIL_HOST=smtp-relay.sendinblue.com
MAIL_PORT=587
[email protected]
MAIL_USERNAME=<[email protected]>
MAIL_PASSWORD=<sendinblue-smtp-key-goes-here>

All containers must be on the same network.
Which is named in the .env file.
If one does not exist yet: docker network create caddy_net

APP_URL in the .env must be set for bookstack to work.
MAIL_ stuff must be set for password reset and new registrations.

Reverse proxy

Caddy v2 is used, details here.

Caddyfile

book.{$MY_DOMAIN} {
    reverse_proxy bookstack:80
}

First run

Default login: [email protected] // password

---

Trouble shooting

• It did not start.
  Ctrl+f in .env file for word example to be replaced with actual domain name. APP_URL has to be set correctly for bookstack to work.
• After update cant see edit tools.
  Clear browsers cookies/cache.
• The test email button in preferences throws error.
  Exec in to the container and printenv to see. Check mail.php to see exact MAIL_ env variables names and default values. Test in Thunderbird your smtp server working or not.

Update

Manual image update:

• docker-compose pull
  
• docker-compose up -d
  
• docker image prune

It is strongly recommended to now add current tags to the images in the compose.
Tags will allow you to easily return to a working state if an update goes wrong.

If there was a major version jump, and bookstack does not work, exec in to the app container and run php artisan migrate
docker container exec -it bookstack /bin/bash
cd /app/www
php artisan migrate

Backup and restore

Backup

Using kopia or borg to make daily snapshot of the entire docker directory.

Restore

• down the containers docker-compose down
  
• delete/move/rename the entire project directory
  
• from the backups copy back the entire project directory
  
• start the containers docker-compose up -d

Backup of just user data

Users data daily export using the official procedure.
For bookstack it means database dump and backing up several directories containing user uploaded files.

Daily kopia/borg backup run takes care of backing up the directories. So only database dump is needed and done with the script.
The created backup sql file is overwritten on every run of the script, but that's ok since kopia/borg are keeping daily snapshots.

Backup script

Placed inside bookstack directory on the host

bookstack-backup-script.sh

#!/bin/bash

# CREATE DATABASE DUMP, bash -c '...' IS USED OTHERWISE OUTPUT > WOULD TRY TO GO TO THE HOST
docker container exec bookstack-db bash -c 'mysqldump -u $MYSQL_USER -p$MYSQL_PASSWORD $MYSQL_DATABASE > $MYSQL_DIR/BACKUP.bookstack.database.sql'

the script must be executable - chmod +x bookstack-backup-script.sh

Cronjob - scheduled backup

Running on the host

• su - switch to root
• crontab -e - add new cron job
  
• 0 22 * * * /home/bastard/docker/bookstack/bookstack-backup-script.sh
  runs it every day at 22:00
• crontab -l - list cronjobs to check

Restore the user data

Assuming clean start and latest images.
Will need BACKUP.bookstack.database.sql and content of bookstack_data/www/
Note that database restore must happen before bookstack app is first run.

• start only the database container: docker-compose up -d bookstack-db
• copy BACKUP.bookstack.database.sql in bookstack/bookstack_db_data/
• restore the database inside the container
  docker container exec --workdir /config bookstack-db bash -c 'mysql -u $MYSQL_USER -p$MYSQL_PASSWORD $MYSQL_DATABASE < BACKUP.bookstack.database.sql'
• now start the app container: docker-compose up -d
• let it run so it creates its file structure
• down the containers docker-compose down
• in bookstack/bookstack_data/www/
  replace directories files,images,uploads and the file .env
  with the ones from the BorgBackup repository
• start the containers: docker-compose up -d
• if there was a major version jump, exec in to the app container and run php artisan migrate
docker container exec -it bookstack /bin/bash
cd /app/www
php artisan migrate

Again, the above steps are based on the official procedure at the time of writing this.