Bookstack Setup

Welcome to the second post in my data stack setup journey! 🎉 My goal is to hustle through setting up all the components so I can get to the good stuff: data and analytics engineering.

But first, I need a documentation server, because, let’s be real—I’m already forgetting where I’ve documented things. 🙃

What is Bookstack?

BookStack describes itself as a “simple, self-hosted, easy-to-use platform for organizing and storing information.” I like to think of it as: a wiki that’s easy to host, simple to back up, and doesn’t make you cry.

What are you using this for?

BookStack is my documentation layer in the data stack. Here’s what I plan to use it for:

Network configurations
Initial data catalog repository
Notes and configs for everything I’m doing

Basically, it’s where my brain will live when it can’t keep up. 🧠

Is Bookstack the best option for documentation?

Honestly? I have no idea. It works for me, and the price is right! (Spoiler: it’s free.)
If you’re looking for the definitive guide to all things documentation, this isn’t it. Move along. 😄

Okay whatever, so how are doing this?

I’m using Docker Compose for pretty much everything. Back in the day, I tried installing tools directly on bare metal. It was a pain to maintain and update.

Docker Compose changed the game. Infrastructure as code? Yes, please.

Will you explain how to setup docker and what docker compose and does?

No.

Great.

It is great, you should check it out!

For this setup, I’m using the official LinuxServer.io BookStack Docker image.

The documentation is pretty great. Here’s the base Docker Compose configuration from their docs:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
---
services:
    bookstack:
    image: lscr.io/linuxserver/bookstack:latest
    container_name: bookstack
    environment:
    - PUID=1000
    - PGID=1000
    - TZ=Etc/UTC
    - APP_URL=
    - APP_KEY=
    - DB_HOST=
    - DB_PORT=3306
    - DB_USERNAME=
    - DB_PASSWORD=
    - DB_DATABASE=
    - QUEUE_CONNECTION= #optional
    volumes:
    - /path/to/bookstack/config:/config
    ports:
    - 6875:80
    restart: unless-stopped

The first thing that sticks out to me is that this image requires a database (that isn’t included). Reading through the documentation BookStack needs a MySQL-compatible database, but one isn’t included in the image. Enter: MariaDB (the first database in this journey).

Now I have a decision to make:

Add the database to the same docker-compose.yaml file.
Set up a separate database container for future reuse.

Since I need this documentation server running yesterday, I’m going with option 1. Let’s flex those Docker skills. 💪

Adding the database: MariaDB 🛢️

LinuxServer.io suggests their MariaDB image, so let’s roll with it:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
services:
  mariadb:
    image: lscr.io/linuxserver/mariadb:latest
    container_name: mariadb
    environment:
      - PUID=1000
      - PGID=1000
      - TZ=Etc/UTC
      - MYSQL_ROOT_PASSWORD=ROOT_ACCESS_PASSWORD
      - MYSQL_DATABASE=USER_DB_NAME #optional
      - MYSQL_USER=MYSQL_USER #optional
      - MYSQL_PASSWORD=DATABASE_PASSWORD #optional
    volumes:
      - /path/to/mariadb/config:/config
    ports:
      - 3306:3306
    restart: unless-stopped

Stitching it together 🧵

Here’s what I’m adding to the docker-compose.yaml file:

Environment variables
The depends_on property so BookStack waits for the database to be ready
A healthcheck to ensure MariaDB finishes initializing before BookStack tries to connect

Here’s the final docker-compose.yaml:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
version: '3.9'

services:
  bookstack:
    image: lscr.io/linuxserver/bookstack:latest
    container_name: bookstack
    depends_on:
      mariadb:
        condition: service_healthy
    environment:
      - PUID=${PUID}
      - PGID=${PGID}
      - TZ=${TZ}
      - APP_URL=${APP_URL}
      - APP_KEY=${APP_KEY}
      - DB_HOST=${DB_HOST}
      - DB_PORT=${DB_PORT}
      - DB_USERNAME=${DB_USERNAME}
      - DB_PASSWORD=${DB_PASSWORD}
      - DB_DATABASE=${DB_DATABASE}
      - QUEUE_CONNECTION=${QUEUE_CONNECTION}
    volumes:
      - ./bookstack/config:/config
    ports:
      - 6875:80
    restart: unless-stopped

  mariadb:
    image: lscr.io/linuxserver/mariadb:latest
    container_name: mariadb
    environment:
      - PUID=${PUID}
      - PGID=${PGID}
      - TZ=${TZ}
      - MYSQL_ROOT_PASSWORD=${MYSQL_ROOT_PASSWORD}
      - MYSQL_DATABASE=${MYSQL_DATABASE}
      - MYSQL_USER=${MYSQL_USER}
      - MYSQL_PASSWORD=${MYSQL_PASSWORD}
    volumes:
      - ./mariadb/config:/config
    ports:
      - 3306:3306
    restart: unless-stopped
    healthcheck:
      test: ["CMD", "mysqladmin", "ping", "-h", "localhost"]
      interval: 10s
      timeout: 5s
      retries: 3

Environment Variables: `.env` File

To keep things tidy, I’m storing all sensitive info in a .env file:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
# Common Settings
PUID=1000
PGID=1000
TZ=America/Chicago

# BookStack Settings
APP_URL=http://your-app-url-here
APP_KEY=base64:YOUR_APP_KEY_HERE
DB_HOST=mariadb
DB_PORT=3306
DB_USERNAME=bookstack
DB_PASSWORD=your-db-password-here
DB_DATABASE=bookstack
QUEUE_CONNECTION=sync

# MariaDB Settings
MYSQL_ROOT_PASSWORD=your-root-password-here
MYSQL_DATABASE=bookstack
MYSQL_USER=bookstack
MYSQL_PASSWORD=your-db-password-here

Running the containers

With the docker-compose.yaml and .env files in place, it’s time to fire it up:

1
docker compose up

Well…. Something’s gone wrong.

Checking the logs, I find this gem:

1
2
bookstack  | An application key is missing, halting init!
bookstack  | You can generate a key with: docker run -it --rm --entrypoint /bin/bash lscr.io/linuxserver/bookstack:latest appkey

No worries—I run the command to generate the key, update the .env file, and try again.

Success! 🎉

And there it is: my shiny new BookStack instance, up and running.

Bookstack Login Screen

Next stop: Probably airflow! Maybe. 🛤️

What is Bookstack?#

What are you using this for?#

Is Bookstack the best option for documentation?#

Okay whatever, so how are doing this?#

Will you explain how to setup docker and what docker compose and does?#

Great.#

Adding the database: MariaDB 🛢️#

Stitching it together 🧵#

Environment Variables: .env File#

Running the containers#

Well…. Something’s gone wrong.#

Success! 🎉#