I like to document my work, generally alongside whatever project I happen to be working on so that I can refer back and keep track of how various things were implemented without reverse engineering my own work.

Originally I had intended for this blog to fit that purpose. Unfortunately it takes me longer than I would like to write these posts and there are details that I have to omit, partially because they are only relevant to myself but also because some of them contain private information.

This led to me start looking for a good method of managing internal documentation.

Reasoning

I spent quite a lot of time trialling several options and eventually settled on BookStackApp.

Unlike the usual Wiki structure, BookStackApp simplifies the organization of data into Books, Chapters and Pages. Simply put, Books contain Chapters and Chapters contain Pages.

There were several close “runner ups” which deserve a mention, these being (in no particular order) Confluence, DokuWiki and MediaWiki.

The reasons I chose BookStackApp over the alternatives are as follows:

There is a demo available if you want to try it out.

Installation

The installation of BookStackApp is very straightforward. I created a new Ubuntu 16.04 LXC container on my Proxmox Hypervisor and ran my usual Ansible configuration playbook (details to follow in a later post).

The specification of the LXC container is as follows:

  • Processor: 1 vCPU(s)
  • Memory: 512.00 MiB
  • SWAP: 512.00 MiB
  • Boot Disk: 16GB

So far this appears to be sufficient. I was then able to run the installation script.

This installs Nginx, MySQL 5.7, & PHP7 with the required PHP extensions. As always I would recommend reading through any installation script rather before running it.

Updating

Updating is done as per the following article: https://www.bookstackapp.com/docs/admin/updates

It is generally recommended to take a backup of the database and file uploads before updating. Personally I simply take a snapshot in Proxmox.

Updating is done using Git with the following command:

git pull origin release && composer install && php artisan migrate && php artisan cache:clear && php artisan view:clear

Summary

I already have 2 books, 7 chapters and 33 pages in BookStackApp and it’s constantly in use.

BookStackApp Homepage