selfhosted-apps-docker/bookstack/readme.md

# Bookstack in docker

###### guide-by-example

![logo](https://i.imgur.com/qDXwqaU.png)

# Purpose & Overview

Documentation and notes.

* [Official site](https://www.bookstackapp.com/)
* [Github](https://github.com/BookStackApp/BookStack)
* [DockerHub](https://hub.docker.com/r/linuxserver/bookstack)

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.</br>
There is no official Dockerhub image so the one maintained by
[linuxserver.io](https://www.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 if you want it

You only need to provide the files.</br>
The directories are created on the first run.

# docker-compose

Dockerhub linuxserver/bookstack 
[example compose.](https://hub.docker.com/r/linuxserver/bookstack)

`docker-compose.yml`
```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

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

networks:
  default:
    name: $DOCKER_MY_NETWORK
    external: true
```

`.env`
```bash
# GENERAL
MY_DOMAIN=example.com
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
MAIL_FROM=book@example.com
MAIL_USERNAME=<registration-email@gmail.com>
SMTP_PASSWORD=<sendinblue-smtp-key-goes-here>
```

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

# Reverse proxy

Caddy v2 is used, details
[here](https://github.com/DoTheEvo/selfhosted-apps-docker/tree/master/caddy_v2).</br>

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

# First run

Default login: `admin@admin.com` // `password`

---

![interface-pic](https://i.imgur.com/cN1GUZw.png)

# Trouble shooting

* It did not start.<br>
  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.
* If after update you cant see edit tools. Clear cookies.

# Update

Manual image update:

- `docker-compose pull`</br>
- `docker-compose up -d`</br>
- `docker image prune`

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

# Backup and restore

#### Backup

Using [kopia](https://github.com/DoTheEvo/selfhosted-apps-docker/tree/master/kopia_backup)
or [borg](https://github.com/DoTheEvo/selfhosted-apps-docker/tree/master/borg_backup)
to make daily snapshot of the entire docker directory.
  
#### Restore

* down the bookstack containers `docker-compose down`</br>
* delete the entire bookstack directory</br>
* from the backup copy back the bookstack directory</br>
* start the containers `docker-compose up -d`

# Backup of just user data

Users data daily export using the
[official procedure.](https://www.bookstackapp.com/docs/admin/backup-restore/)</br>
For bookstack it means database dump and backing up several directories
containing user uploaded files.

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

#### Create a backup script

Placed inside `bookstack` directory on the host

`bookstack-backup-script.sh`
```bash
#!/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

Running on the host, so that the script will be periodically run.

* `su` - switch to root
* `crontab -e` - add new cron job</br>
* `0 22 * * * /home/bastard/docker/bookstack/bookstack-backup-script.sh`</br>
  runs it every day [at 22:00](https://crontab.guru/#0_22_*_*_*) 
* `crontab -l` - list cronjobs to check

# 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`
* copy `BACKUP.bookstack.database.sql` in `bookstack/bookstack_db_data/`
* restore the database inside the container</br>
  `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/`</br>
  replace directories `files`,`images`,`uploads` and the file `.env`</br>
  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`</br>
  `docker container exec -it bookstack /bin/bash`</br>
  `cd /app/www`</br>
  `php artisan migrate`

Again, the above steps are based on the 
[official procedure](https://www.bookstackapp.com/docs/admin/backup-restore/)
at the time of writting this.