Bookstack in docker

guide by example

Purpose

Documentation and notes.

Files and directory structure

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

docker-compose

Dockerhub linuxserver/bookstack example compose.

docker-compose.yml

version: "2"
services:

  bookstack_db:
    image: linuxserver/mariadb
    container_name: bookstack_db
    hostname: bookstack_db
    environment:
      - TZ
      - PUID
      - PGID
      - MYSQL_ROOT_PASSWORD
      - MYSQL_DATABASE
      - MYSQL_USER
      - MYSQL_PASSWORD
    volumes:
      - ./bookstack-data-db:/config
    restart: unless-stopped

  bookstack:
    image: linuxserver/bookstack
    container_name: bookstack
    hostname: bookstack
    environment:
      - TZ
      - PUID
      - PGID
      - DB_HOST
      - DB_USER
      - DB_PASS
      - DB_DATABASE
      - APP_URL
      - MAIL_DRIVER
      - MAIL_HOST
      - MAIL_PORT
      - MAIL_FROM
      - MAIL_USERNAME
      - MAIL_PASSWORD
      - MAIL_ENCRYPTION
    volumes:
      - ./bookstack-data:/config
    restart: unless-stopped
    depends_on:
      - bookstack_db

networks:
  default:
    external:
      name: $DEFAULT_NETWORK

.env

# GENERAL
MY_DOMAIN=blabla.org
DEFAULT_NETWORK=caddy_net
TZ=Europe/Prague

# BOOKSTACK-MARIADB
PUID=1000
PGID=1000
MYSQL_ROOT_PASSWORD=bookstack
MYSQL_DATABASE=bookstack
MYSQL_USER=bookstack
MYSQL_PASSWORD=bookstack

# BOOKSTACK
PUID=1000
PGID=1000
DB_HOST=bookstack_db
DB_USER=bookstack
DB_PASS=bookstack
DB_DATABASE=bookstack

# USING SENDGRID FOR SENDING EMAILS
APP_URL=https://book.blabla.org
MAIL_DRIVER=smtp
MAIL_HOST=smtp.sendgrid.net
MAIL_PORT=465
MAIL_FROM=book@blabla.org
MAIL_USERNAME=apikey
MAIL_PASSWORD=SG.2FA24asaddasdasdasdsadasdasdassadDEMBzuh9e43
MAIL_ENCRYPTION=SSL

All containers must be on the same network.
If one does not exist yet: docker network create caddy_net

Reverse proxy

Caddy v2 is used, details here

Caddyfile

{
    # acme_ca https://acme-staging-v02.api.letsencrypt.org/directory
}

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

Update

watchtower updates the image automaticly
manual image update
docker-compose pull
docker-compose up -d
docker image prune

Backup and restore

backup using borgbackup setup that makes daily snapshot of the entire directory
restore
down the bookstack containers docker-compose down
delete the entire bookstack directory
from the backup copy back the bookstack directortory
start the container docker-compose up -d

Backup of just user data

user-data daily export using the official procedure.
For bookstack it means database dump and backing up several directories containing user uploaded files. The created backup files are overwriten on every run of the script, but borg backup is daily making snapshot of the entire directory.

create a 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'

# ARCHIVE UPLOADED FILES
docker container exec bookstack tar -czPf /config/BACKUP.bookstack.uploaded-files.tar.gz /config/www/

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

cronjob on the host
crontab -e - add new cron job
0 2 * * * /home/bastard/docker/bookstack/bookstack-backup-script.sh - run it at 02:00
crontab -l - list cronjobs

Restore the user data

Assuming clean start, first restore the database before running the app container.

start only the database container: docker-compose up -d bookstack_db
have BACKUP.bookstack.database.sql mounted in by placing it in bookstack/bookstack-data
exec in to the container and restore the database
docker container exec -it bookstack_db /bin/bash
cd /config
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 and uploads and the file .env with the ones from the archive BACKUP.bookstack.uploaded-files.tar.gz
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 /var/www/html/
php artisan migrate