Step-by-Step Guide to Self-Hosting BookStack on Your Home Server

This comprehensive guide will take you through the process of self-hosting BookStack on your home server, providing you with an efficient and secure way to manage your content.

Mar 11, 2023

👋 Hi, this is Shishir with a free, bonus issue of The Digital Den newsletter. In every issue, I empower you to take control of your data and technology by exploring the exciting world of self-hosted applications.

If you’re not a subscriber, you have missed several members-only guides. Subscribe to get knowledge-full guides every week. 👇

In this comprehensive guide, learn how to self-host BookStack on your home server and take control of your content management. Follow easy step-by-step instructions to set up your own instance of this popular open-source documentation platform, allowing you to create, organize, and share your information with ease.

Say goodbye to the limitations of cloud-based services and hello to a personalized content management system that you can fully customize and control. Start today and streamline your content management process!

*Step-by-Step Guide to Self-Hosting BookStack on Your Home Server*

Introduction to BookStack

Bookstack is a free and open-source web-based application used for creating and managing documentation. It provides a simple and intuitive interface for creating, organizing, and sharing content. Bookstack is primarily used by businesses, educational institutions, and individuals who need to create and maintain documentation for their projects or work.

Bookstack is built using PHP and uses MySQL as its backend database. It allows users to create books, chapters, and pages to organize their content. The application supports rich text formatting, images, and file attachments, making it easy to create visually appealing and informative documentation. Bookstack also provides granular access control, so you can define who has access to your content and what they can do with it.

Docker Images for BookStack

There are several different Docker images available for running BookStack application. Here are some of the most commonly used images:

1. Solidnerd/bookstack: This is a community-maintained Docker image that includes BookStack, Apache, and PHP. Unlike the official BookStack image, this image does not include a MySQL server.

3. Linuxserver/bookstack: This is another community-maintained Docker image that includes BookStack, Apache, PHP, and MySQL. It is designed to be lightweight and easy to set up.

Each of these Docker images has its own strengths and weaknesses, and the best choice for your use case will depend on your specific needs and preferences.

Setup BookStack in Docker

Step 1: Install Docker and Docker Compose

To get started, you'll need to install Docker and Docker Compose on your machine. You can find installation instructions for Docker at https://docs.docker.com/get-docker/ and for Docker Compose at https://docs.docker.com/compose/install/.

Step 2: Create a new directory for your BookStack Docker Compose files

Create a new directory to store your BookStack Docker Compose files. You can do this by opening a terminal and running the following command:

mkdir bookstack 
cd bookstack

Step 3: Create a Docker Compose file

Next, you'll need to create a Docker Compose file named docker-compose.yml in your bookstack directory. You can do this by running the following command:

nano docker-compose.yml

Then, copy and paste the following code into the file:

version: '3'
services:
  bookstack:
    image: solidnerd/bookstack
    container_name: bookstack
    restart: always
    ports:
      - "8080:80"
    volumes:
      - ./data:/var/www/html/public/uploads
      - ./env:/var/www/html/.env
    environment:
      - PUID=1000
      - PGID=1000
      - APP_URL=http://localhost:8080
      - DB_HOST=db
      - DB_DATABASE=bookstack
      - DB_USERNAME=bookstack_user
      - DB_PASSWORD=secret
    depends_on:
      - db
  db:
    image: mysql:5.7
    container_name: bookstack-mysql
    restart: always
    environment:
      - MYSQL_DATABASE=bookstack
      - MYSQL_USER=bookstack_user
      - MYSQL_PASSWORD=secret
      - MYSQL_RANDOM_ROOT_PASSWORD=yes
    volumes:
      - ./db:/var/lib/mysql

In the above code, we have defined two services, bookstack and db. The bookstack service will run the BookStack application, while the db service will run a MySQL database container.

The bookstack service uses the solidnerd/bookstack image and sets the container name to bookstack. It also sets some environment variables such as PUID and PGID, which define the user and group IDs for the container. These values will be used to set the ownership of the files in the mounted volume.

The bookstack service also defines a volume to persist the configuration files in the ./data directory on the host machine. The service also maps port 8080 on the host to port 80 inside the container.

The db service uses the mysql image and sets the container name to bookstack-mysql. It also sets some environment variables such as MYSQL_RANDOM_ROOT_PASSWORD, MYSQL_DATABASE, MYSQL_USER, and MYSQL_PASSWORD to set up the MySQL database. It also defines a volume to persist the database data in the ./db directory on the host machine.

Step 4: Create a data directory

Next, create a directory named data in your bookstack directory:

mkdir data

This directory will be used to store uploaded files and other data generated by BookStack.

Step 5: Create an env file

Create a file named env in your bookstack directory:

nano env

Then, copy and paste the following code into the file:

APP_NAME=BookStack
APP_ENV=production
APP_DEBUG=false
APP_LOG=daily
APP_URL=http://localhost:8080

DB_CONNECTION=mysql
DB_HOST=db
DB_PORT=3306
DB_DATABASE=bookstack
DB_USERNAME=bookstack_user
DB_PASSWORD=secret

MAIL_DRIVER=log

This file sets up some environment variables that BookStack will use to connect to the MySQL database and to configure various settings.

Step 6: Start the Docker containers

You're now ready to start the Docker containers. To do this, run the following command in your bookstack directory:

docker-compose up -d

This command will start the BookStack and MySQL containers in detached mode (in the background). Docker will download the necessary images if they are not already present on your machine.

Step 7: Access BookStack

Once the containers are running, you can access BookStack by navigating to http://localhost:8080 in your web browser. You should see the BookStack login page.

Step 8: Log in to BookStack

Email: admin@admin.com
Password: password

Step 9: Follow the on-screen instructions

Finally, follow the on-screen instructions to complete the installation of BookStack.

That's it! You now have BookStack up and running in your Docker.

Backup and Restore Self-Hosted BookStack

Backing up and restoring BookStack data via mysqldump is a straightforward process. Here are the steps you need to follow:

Backing up BookStack data via mysqldump:

Log in to your server as the root user or with a sudo-enabled user.
Open a terminal window.
Use the following command to create a backup of your BookStack database:

mysqldump -u [database_user] -p [database_name] > [backup_file.sql]

Replace [database_user] with the username of your BookStack database user, [database_name] with the name of your BookStack database, and [backup_file.sql] with the name you want to give your backup file.

Enter the password for your BookStack database user when prompted.
Wait for the command to complete. Once it's finished, you should have a backup file in your current directory.

Restoring BookStack data via mysqldump:

Log in to your server as the root user or with a sudo-enabled user.
Open a terminal window.
Use the following command to restore your BookStack database from a backup file:

mysql -u [database_user] -p [database_name] < [backup_file.sql]

Replace [database_user] with the username of your BookStack database user, [database_name] with the name of your BookStack database, and [backup_file.sql] with the name of the backup file you want to restore from.

Enter the password for your BookStack database user when prompted.
Wait for the command to complete. Once it's finished, your BookStack database should be restored from the backup file.

Here's an example of how you could use these commands:

Backing up BookStack data:

mysqldump -u bookstack_user -p bookstack > bookstack_backup.sql

Restoring BookStack data:

mysql -u bookstack_user -p bookstack < bookstack_backup.sql

Note: It's important to regularly back up your BookStack data to ensure you don't lose any important information.

High Level Architecture of BookStack

The architecture of BookStack consists of different components that work together to provide its functionality.

Here's a high-level architecture diagram of BookStack:

The architecture diagram shows that BookStack is a web-based application that runs on a web server. The web server communicates with the database, search, and object storage services to store and retrieve data. The cache service is used to improve performance by storing frequently accessed data in memory. The file storage service is used to store uploaded files, and the email service is used to send notifications and alerts to users.

Overall, the architecture of BookStack is designed to be scalable, reliable, and easy to use, making it a popular choice for organizations that need to manage and share information.

In the End

Final Docker Compose file with BookStack and MySQL is as below.

version: '3'
services:
  bookstack:
    image: solidnerd/bookstack
    container_name: bookstack
    restart: always
    ports:
      - "8080:80"
    volumes:
      - ./data:/var/www/html/public/uploads
      - ./env:/var/www/html/.env
    environment:
      - PUID=1000
      - PGID=1000
      - APP_URL=http://localhost:8080
      - DB_HOST=db
      - DB_DATABASE=bookstack
      - DB_USERNAME=bookstack_user
      - DB_PASSWORD=secret
    depends_on:
      - db
  db:
    image: mysql:5.7
    container_name: bookstack-mysql
    restart: always
    environment:
      - MYSQL_DATABASE=bookstack
      - MYSQL_USER=bookstack_user
      - MYSQL_PASSWORD=secret
      - MYSQL_RANDOM_ROOT_PASSWORD=yes
    volumes:
      - ./db:/var/lib/mysql

All source file(s) used above are present at my Gitlab project.

The Digital Den