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.
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.
The reasons I chose BookStackApp over the alternatives are as follows:
- Very simple & straightforward WebUI
- Fully free and open source (MIT License)
- Easily configurable
- Simple requirements (PHP & MySQL)
- Easy installation and updating
- Looks great out of the box
- Supports markdown with a WYSIWYG editor
- Under active development and accepts input from the community
There is a demo available if you want to try it out.
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 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:
I already have 2 books, 7 chapters and 33 pages in BookStackApp and it’s constantly in use.