diff --git a/manuscript/images/bookstack.png b/manuscript/images/bookstack.png new file mode 100644 index 0000000..8e148c6 Binary files /dev/null and b/manuscript/images/bookstack.png differ diff --git a/manuscript/recipies/bookstack.md b/manuscript/recipies/bookstack.md new file mode 100644 index 0000000..9420921 --- /dev/null +++ b/manuscript/recipies/bookstack.md @@ -0,0 +1,150 @@ +hero: Heroic Hero + +# BookStack + +BookStack is a simple, self-hosted, easy-to-use platform for organising and storing information. + +A friendly middle ground between heavyweights like MediaWiki or Confluence and [Gollum](/recipies/gollum/), BookStack relies on a database backend (so searching and versioning is easy), but limits itself to a pre-defined, 3-tier structure (book, chapter, page). The result is a lightweight, approachable personal documentation stack, which includes search and Markdown editing. + +![BookStack Screenshot](../images/bookstack.png) + +I like to protect my public-facing web UIs with an [oauth_proxy](/reference/oauth_proxy), ensuring that if an application bug (or a user misconfiguration) exposes the app to unplanned public scrutiny, I have a second layer of defense. + +## Ingredients + +1. [Docker swarm cluster](/ha-docker-swarm/design/) with [persistent shared storage](/ha-docker-swarm/shared-storage-ceph.md) +2. [Traefik](/ha-docker-swarm/traefik_public) configured per design +3. DNS entry for the hostname you intend to use, pointed to your [keepalived](ha-docker-swarm/keepalived/) IP + +## Preparation + +### Setup data locations + +We'll need several directories to bind-mount into our container, so create them in /var/data/bookstack: + +``` +mkdir -p /var/data/bookstack/database-dump +mkdir -p /var/data/runtime/bookstack/db +``` + +### Prepare environment + +Create bookstack.env, and populate with the following variables +``` +OAUTH2_PROXY_CLIENT_ID= +OAUTH2_PROXY_CLIENT_SECRET= +OAUTH2_PROXY_COOKIE_SECRET= + +# For MariaDB/MySQL database +MYSQL_RANDOM_ROOT_PASSWORD=true +MYSQL_DATABASE=bookstack +MYSQL_USER=bookstack +MYSQL_PASSWORD=secret + +# Bookstack-specific variables +DB_HOST=bookstack_db:3306 +DB_DATABASE=bookstack +DB_USERNAME=bookstack +DB_PASSWORD=secret +``` + +### Setup Docker Swarm + +Create a docker swarm config file in docker-compose syntax (v3), something like this: + +!!! tip + I share (_with my [patreon patrons](https://www.patreon.com/funkypenguin)_) a private "_premix_" git repository, which includes necessary docker-compose and env files for all published recipes. This means that patrons can launch any recipe with just a ```git pull``` and a ```docker stack deploy``` 👍 + + +``` +version: '3' + +services: + + db: + image: mariadb:10 + env_file: /var/data/config/bookstack/bookstack.env + networks: + - internal + volumes: + - /var/data/runtime/bookstack/db:/var/lib/mysql + + proxy: + image: a5huynh/oauth2_proxy + env_file : /var/data/config/bookstack/bookstack.env + networks: + - internal + - traefik_public + deploy: + labels: + - traefik.frontend.rule=Host:bookstack.funkypenguin.co.nz + - traefik.docker.network=traefik_public + - traefik.port=4180 + volumes: + - /var/data/config/bookstack/authenticated-emails.txt:/authenticated-emails.txt + command: | + -cookie-secure=false + -upstream=http://app + -redirect-url=https://bookstack.funkypenguin.co.nz + -http-address=http://0.0.0.0:4180 + -email-domain=funkypenguin.co.nz + -provider=github + -authenticated-emails-file=/authenticated-emails.txt + + app: + image: solidnerd/bookstack + env_file: /var/data/config/bookstack/bookstack.env + networks: + - internal + + db-backup: + image: mariadb:10 + env_file: /var/data/config/bookstack/bookstack.env + volumes: + - /var/data/bookstack/database-dump:/dump + - /etc/localtime:/etc/localtime:ro + entrypoint: | + bash -c 'bash -s < /dump/dump_\`date +%d-%m-%Y"_"%H_%M_%S\`.sql.gz + (ls -t /dump/dump*.sql.gz|head -n $$BACKUP_NUM_KEEP;ls /dump/dump*.sql.gz)|sort|uniq -u|xargs rm -- {} + sleep $$BACKUP_FREQUENCY + done + EOF' + networks: + - internal + +networks: + traefik_public: + external: true + internal: + driver: overlay + ipam: + config: + - subnet: 172.16.33.0/24 +``` + +!!! note + Setup unique static subnets for every stack you deploy. This avoids IP/gateway conflicts which can otherwise occur when you're creating/removing stacks a lot. See [my list](/reference/networks/) here. + + + +## Serving + +### Launch Bookstack stack + +Launch the BookStack stack by running ```docker stack deploy bookstack -c ``` + +Log into your new instance at https://**YOUR-FQDN**, authenticate with oauth_proxy, and then login with username 'admin@admin.com' and password 'password'. + +## Chef's Notes + +1. If you wanted to expose the BookStack UI directly, you could remove the oauth2_proxy from the design, and move the traefik_public-related labels directly to the bookstack container. You'd also need to add the traefik_public network to the bookstack container. + +### Tip your waiter (donate) 👏 + +Did you receive excellent service? Want to make your waiter happy? (_..and support development of current and future recipes!_) See the [support](/support/) page for (_free or paid)_ ways to say thank you! 👏 + +### Your comments? 💬 diff --git a/manuscript/recipies/template.md b/manuscript/recipies/template.md index d9aa496..aa671d1 100644 --- a/manuscript/recipies/template.md +++ b/manuscript/recipies/template.md @@ -11,7 +11,7 @@ Details ## Ingredients 1. [Docker swarm cluster](/ha-docker-swarm/design/) with [persistent shared storage](/ha-docker-swarm/shared-storage-ceph.md) -2. [Traefik](/ha-docker-swarm/traefik) configured per design +2. [Traefik](/ha-docker-swarm/traefik_public) configured per design 3. DNS entry for the hostname you intend to use, pointed to your [keepalived](ha-docker-swarm/keepalived/) IP ## Preparation @@ -65,13 +65,13 @@ services: image: a5huynh/oauth2_proxy env_file: /var/data/wekan/wekan.env networks: - - traefik + - traefik_public - internal deploy: labels: - - traefik.frontend.rule=Host:wekan.example.com - - traefik.docker.network=traefik - - traefik.port=4180 + - traefik_public.frontend.rule=Host:wekan.example.com + - traefik_public.docker.network=traefik_public + - traefik_public.port=4180 command: | -cookie-secure=false -upstream=http://wekan:80 @@ -87,7 +87,7 @@ services: env_file: /var/data/wekan/wekan.env networks: - traefik: + traefik_public: external: true internal: driver: overlay @@ -111,7 +111,7 @@ Log into your new instance at https://**YOUR-FQDN**, with user "root" and the pa ## Chef's Notes -1. If you wanted to expose the Wekan UI directly, you could remove the oauth2_proxy from the design, and move the traefik-related labels directly to the wekan container. You'd also need to add the traefik network to the wekan container. +1. If you wanted to expose the Wekan UI directly, you could remove the oauth2_proxy from the design, and move the traefik_public-related labels directly to the wekan container. You'd also need to add the traefik_public network to the wekan container. ### Tip your waiter (donate) 👏 diff --git a/manuscript/reference/networks.md b/manuscript/reference/networks.md index ea5889a..fcb634e 100644 --- a/manuscript/reference/networks.md +++ b/manuscript/reference/networks.md @@ -32,6 +32,7 @@ Network | Range [Munin](https://geek-cookbook.funkypenguin.co.nz/recipies/munin/) | 172.16.24.0/24 [Masari Mining Pool](https://geek-cookbook.funkypenguin.co.nz/recipies/cryptonote-mining-pool/masari/) | 172.16.25.0/24 [Athena Mining Pool](https://geek-cookbook.funkypenguin.co.nz/recipies/cryptonote-mining-pool/athena/) | 172.16.26.0/24 +[Bookstack](https://geek-cookbook.funkypenguin.co.nz/recipies/bookstack/) | 172.16.33.0/24 ## Chef's Notes diff --git a/mkdocs.yml b/mkdocs.yml index 4cf40f2..4729604 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -75,6 +75,7 @@ pages: - Wallabag: recipies/wallabag.md - Turtle Pool: recipies/turtle-pool.md - Menu: + - Bookstack: recipies/bookstack.md - Ghost: recipies/ghost.md - GitLab: recipies/gitlab.md - GitLab Runner: recipies/gitlab-runner.md