selfhosted-apps-docker/bookstack/readme.md

224 lines
6.4 KiB
Markdown
Raw Normal View History

2020-04-09 22:52:11 +00:00
# Bookstack in docker
2020-05-18 22:49:18 +00:00
###### guide-by-example
2020-04-09 22:52:11 +00:00
![logo](https://i.imgur.com/qDXwqaU.png)
2020-05-06 23:13:02 +00:00
# Purpose & Overview
2020-04-09 22:52:11 +00:00
Documentation and notes.
* [Official site](https://www.bookstackapp.com/)
* [Github](https://github.com/BookStackApp/BookStack)
2020-04-10 02:40:54 +00:00
* [DockerHub](https://hub.docker.com/r/linuxserver/bookstack)
2020-04-09 22:52:11 +00:00
2020-05-06 23:13:02 +00:00
BookStack is a modern, open source, good looking wiki platform
2020-05-07 19:45:04 +00:00
for storing and organizing information and documentation.
2020-05-06 23:13:02 +00:00
2020-05-07 19:45:04 +00:00
Written in PHP, with MySQL database for the user data.</br>
There is no official Dockerhub image so the one maintained by
2020-05-06 23:13:02 +00:00
[linuxserver.io](https://www.linuxserver.io/) is used,
which uses nginx as a web server.
2020-04-24 22:52:32 +00:00
# Files and directory structure
2020-04-09 22:52:11 +00:00
2020-04-25 22:49:11 +00:00
```
2020-05-01 09:38:43 +00:00
/home/
└── ~/
└── docker/
└── bookstack/
├── bookstack-data/
├── bookstack-db-data/
├── .env
├── docker-compose.yml
└── bookstack-backup-script.sh
2020-04-25 22:49:11 +00:00
```
2020-04-09 22:52:11 +00:00
2020-05-07 19:45:04 +00:00
* `bookstack-data/` - a directory where bookstack will store its web app data
* `bookstack-db-data/` - a directory where bookstack will store its MySQL database data
2020-05-22 16:05:03 +00:00
* `.env` - a file containing environment variables for docker compose
2020-05-22 16:22:45 +00:00
* `docker-compose.yml` - a docker compose file, telling docker how to run the containers
2020-05-07 19:45:04 +00:00
* `bookstack-backup-script.sh` - a backup script if you want it
You only need to provide the files.</br>
The directories are created by docker compose on the first run.
2020-04-24 22:52:32 +00:00
# docker-compose
2020-04-09 22:52:11 +00:00
2020-05-01 09:51:20 +00:00
Dockerhub linuxserver/bookstack
[example compose.](https://hub.docker.com/r/linuxserver/bookstack)
2020-04-25 22:49:11 +00:00
`docker-compose.yml`
```yml
version: "2"
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
networks:
default:
external:
2020-05-20 18:29:12 +00:00
name: $DOCKER_MY_NETWORK
2020-04-25 22:49:11 +00:00
```
`.env`
```bash
# GENERAL
2020-05-16 13:18:21 +00:00
MY_DOMAIN=example.com
2020-05-20 18:29:12 +00:00
DOCKER_MY_NETWORK=caddy_net
2020-05-02 20:48:23 +00:00
TZ=Europe/Bratislava
2020-04-25 22:49:11 +00:00
#LINUXSERVER.IO
PUID=1000
PGID=1000
# BOOKSTACK-MARIADB
MYSQL_ROOT_PASSWORD=bookstack
MYSQL_DATABASE=bookstack
MYSQL_USER=bookstack
MYSQL_PASSWORD=bookstack
# BOOKSTACK
2020-05-20 17:20:01 +00:00
APP_URL=https://book.example.com
2020-04-25 22:49:11 +00:00
DB_HOST=bookstack-db
DB_USER=bookstack
DB_PASS=bookstack
DB_DATABASE=bookstack
# USING SENDGRID FOR SENDING EMAILS
2020-05-20 18:38:44 +00:00
MAIL_ENCRYPTION=SSL
2020-04-25 22:49:11 +00:00
MAIL_DRIVER=smtp
MAIL_HOST=smtp.sendgrid.net
MAIL_PORT=465
2020-05-16 13:18:21 +00:00
MAIL_FROM=book@example.com
2020-04-25 22:49:11 +00:00
MAIL_USERNAME=apikey
2020-05-20 18:40:28 +00:00
SMTP_PASSWORD=<sendgrid-api-key-goes-here>
2020-04-25 22:49:11 +00:00
```
**All containers must be on the same network**.</br>
2020-05-10 21:48:51 +00:00
Which is named in the `.env` file.</br>
2020-04-25 22:49:11 +00:00
If one does not exist yet: `docker network create caddy_net`
2020-04-10 23:51:47 +00:00
2020-04-24 22:52:32 +00:00
# Reverse proxy
2020-04-09 22:52:11 +00:00
2020-05-01 09:51:20 +00:00
Caddy v2 is used, details
[here](https://github.com/DoTheEvo/selfhosted-apps-docker/tree/master/caddy_v2).</br>
2020-04-09 22:52:11 +00:00
2020-04-25 22:49:11 +00:00
`Caddyfile`
```
book.{$MY_DOMAIN} {
reverse_proxy bookstack:80
}
```
2020-04-09 22:52:11 +00:00
2020-05-20 17:15:19 +00:00
# First run
Default login: `admin@admin.com` // `password`
2020-04-16 22:05:54 +00:00
---
2020-04-10 23:51:47 +00:00
![interface-pic](https://i.imgur.com/cN1GUZw.png)
2020-04-09 22:52:11 +00:00
2020-04-24 22:52:32 +00:00
# Update
2020-04-10 02:40:54 +00:00
2020-05-09 00:49:15 +00:00
[Watchtower](https://github.com/DoTheEvo/selfhosted-apps-docker/tree/master/watchtower)
updates the image automatically.
2020-04-09 22:52:11 +00:00
2020-05-09 00:49:15 +00:00
Manual image update:
- `docker-compose pull`</br>
- `docker-compose up -d`</br>
- `docker image prune`
2020-04-09 22:52:11 +00:00
2020-04-24 22:52:32 +00:00
# Backup and restore
2020-04-09 22:52:11 +00:00
2020-05-07 19:45:04 +00:00
#### Backup
Using [borg](https://github.com/DoTheEvo/selfhosted-apps-docker/tree/master/borg_backup)
that makes daily snapshot of the entire 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`
2020-04-09 22:52:11 +00:00
2020-04-24 22:52:32 +00:00
# Backup of just user data
2020-04-09 22:52:11 +00:00
2020-05-07 19:45:04 +00:00
Users data daily export using the
[official procedure.](https://www.bookstackapp.com/docs/admin/backup-restore/)</br>
2020-04-24 22:52:32 +00:00
For bookstack it means database dump and backing up several directories
containing user uploaded files.
2020-05-07 19:45:04 +00:00
Daily [borg](https://github.com/DoTheEvo/selfhosted-apps-docker/tree/master/borg_backup) run
2020-04-24 22:52:32 +00:00
takes care of backing up the directories.
2020-05-07 19:45:04 +00:00
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 borg is making daily snapshots.
#### Create a backup script
2020-04-09 22:52:11 +00:00
2020-05-07 19:45:04 +00:00
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'
```
2020-04-09 22:52:11 +00:00
2020-05-07 19:45:04 +00:00
the script must be **executable** - `chmod +x bookstack-backup-script.sh`
2020-04-09 22:52:11 +00:00
2020-05-07 19:45:04 +00:00
#### Cronjob
2020-04-09 22:52:11 +00:00
2020-05-07 19:45:04 +00:00
Running on the host, so that the script will be periodically run.
2020-04-09 22:52:11 +00:00
2020-05-07 19:45:04 +00:00
* `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
2020-04-09 22:52:11 +00:00
2020-04-24 22:52:32 +00:00
# Restore the user data
2020-04-09 22:52:11 +00:00
2020-05-07 19:45:04 +00:00
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 /var/www/html/`</br>
`php artisan migrate`
Again, the above steps are based on the
[official procedure.](https://www.bookstackapp.com/docs/admin/backup-restore/)