BookStack is a simple, self-hosted, easy-to-use platform for organizing and storing information.
Let’s start with actual deployment…
Please make sure you should fulfill the below requirements before proceeding to the actual deployment.
Docker Swarm Cluster with GlusterFS as persistent tool.
Traefik as reverse proxy to expose micro-services to external.
Database stack to host application databases.
If you are looking to self-host your product documents to reduce the footprint of ticket management or want to manage project documentation for internal teams or want to have a private repository, BookStack is the best solution to consider.
BookStack is an opinionated wiki system that provides a pleasant and simple out of the box experience.
Why is BookStack
BookStack is a simple, easy-to-use platform for storing and organizing information and documentation.
New users only require basic word-processing skills to get involved in creating content on BookStack.
BookStack is not designed as an extensible platform to be used for purposes that differ to the statement above.
In regards to development philosophy, BookStack has a relaxed, open & positive approach. At the end of the day, this is free software developed and maintained by people donating their own free time.
The principles of storing information within BookStack is based on the ideas of a normal stack of books. Just like normal books, BookStack books can contain chapters and pages. You start off by creating a book that acts as the highest level of categorization. Ideally, you’d have separate books for separate topics.
Within a book, you can directly create pages or you can first create chapters. Chapters provide an additional level of page grouping to keep pages organized but are optional.
Once you start to stack up books you can start to use Bookshelves to organize your Books. Bookshelves can contain multiple books and a single book could be placed on multiple Bookshelves.
BookStack should provide advanced power features to those that desire it but they should not interfere with the core simple user experience.
Here are some of the features that you’ll love
BookStack is fully free and open, MIT licensed. There is no cost to downloading and installing your own instance.
Simplicity has been the top priority. It has a simple WYSIWYG interface & content is broken into Books, Chapters, and Pages.
The content is fully searchable. Search at book level or across all books, chapters & pages. You can link directly to any paragraph to keep documentation connected.
BookStack is built using PHP, on top of the Laravel framework and it uses MySQL to store data. It can run happily on a $5 Digital Ocean VPS.
You can set up BookStack to suit your use case, change the name, Logo, and registration options. You can also change whether the whole system is publicly viewable or not.
Along with the default email/password login, social providers such as GitHub, Google, Slack, AzureAD, and more can be used. Okta and LDAP options are available for enterprise environments.
Some other features include below as well apart from the above list
Optional Markdown Editor
Persist BookStack Data
Containers are fast to deploy and make efficient use of system resources. Developers get application portability and programmable image management and the operations team gets standard run time units of deployment and management.
With all the known benefits of containers, there is one common misperception that the containers are ephemeral, which means if we restart the container or in case of any issues with it, we lose all the data for that particular container. They are only good for stateless micro-service applications and that it’s not possible to containerize stateful applications.
I am going to use GlusterFS to overcome the ephemeral behavior of Containers.
I already set up a replicated GlusterFS volume to have data replicated throughout the cluster if I would like to have some persistent data.
The below diagram explains how the replicated volume works.
Volume will be mounted on all the nodes, and when a file is written to the
/mntpartition, data will be replicated to all the nodes in the Cluster
In case any one of the nodes fails, the application automatically starts on another node without losing any data and that’s the beauty of the replicated volume.
Persistent application state or data needs to survive application restarts and outages. We are storing the data or state in GlusterFS and had periodic backups performed on it.
We will use a backup of the volume to spin a new application container anywhere else in case of unexpected issues occur in the current environment.
I am going to persist
/var/www/bookstack/storage/uploads directories of BookStack for disaster recovery.
Create folders in
/mnt directory to persistent BookStack data folders.
sudo mkdir -p buploads
sudo mkdir -p bsuploads
Please watch the below video for Glusterfs Installation
Prepare BookStack Environment
Create a folder in
/opt directory to place configuration file, i.e,
.yml file for BookStack.
Use the below commands to create the folder.
sudo mkdir -p bookstack
sudo touch bookstack.yml
BookStack Docker Compose
bookstack.yml created earlier with nano editor using
sudo nano bookstack.yml
Copy and paste the below code in
Here is the
docker compose file for
constraints: [node.role == worker]
As I mentioned in the prerequisites, I used MariaDB as a back-end storage system for BookStack which was deployed earlier to our Docker Swarm environment.
There are some configurations we can use while composing BookStack. Please go through this link for the full set of configuration options.
Community docker setups are available for those that would prefer to use a containerized version of BookStack:
Deploy BookStack using Docker Compose
Please make sure we have created a wiki database before deploying BookStack using the MariaDB stack deployed earlier.
Now it’s time to deploy our docker-compose file above,
bookstack.yml using the below command
docker stack deploy --compose-file bookstack.yml bookstack
You can give it any name for the stack. I just named it as
Check the status of the stack by using
docker stack ps bookstack
Now open any browser and type
bookstack.example.com (whatever host URL used in the BookStack configuration in the docker-compose file) to access the instance.
Make sure that you have DNS entry for your application (bookstack.example.com) in your DNS Management Application.
You will be greeted with the below screen to the login screen of BookStack. Use default credentials (email@example.com / password) to login.
Change Admin email address and password in Edit Profile settings.
Hope you enjoyed this tutorial, please give your input/thought on it by commenting below. It would help me to bring more articles that focus on Open Source to self-host.
Stay tuned for other deployments in coming posts… 🙄