Installing BookStack on the Raspberry Pi

Ben
Ben
@benjislab

BookStack is a free and open-source platform for creating and managing documentation. It offers an intuitive interface for organizing your content into books, chapters, and pages, making it an ideal solution for personal notes, project documentation, or team collaboration. In this guide, we will walk you through the steps to install BookStack on your Raspberry Pi.

Equipment Needed

  • Raspberry Pi (preferably Raspberry Pi 3 or 4)
  • MicroSD card (at least 16GB)
  • MicroSD card reader
  • Internet connection
  • Power supply for Raspberry Pi

Step 1: Prepare Your Raspberry Pi

Install Raspberry Pi OS

  1. Download Raspberry Pi OS:

Download the latest version of Raspberry Pi OS Lite from the official Raspberry Pi website.

  1. Write the OS to the MicroSD Card:

Use Raspberry Pi Imager or Balena Etcher to write the Raspberry Pi OS image to your MicroSD card.

  1. Set Up the Raspberry Pi:

Insert the MicroSD card into your Raspberry Pi, connect it to a monitor, keyboard, and power it on. Follow the setup instructions to configure your Raspberry Pi.

  1. Update Your System:

Ensure your Raspberry Pi is up-to-date with the latest software and security patches.

sudo apt update
sudo apt upgrade

Step 2: Install Required Packages

BookStack requires several dependencies to function correctly. Install these packages using the following commands.

  1. Install Apache, MariaDB, and PHP:
sudo apt install apache2 mariadb-server mariadb-client
sudo apt install php php-mysql php-xml php-mbstring php-zip php-gd php-curl php-intl
  1. Install Git and Composer:
sudo apt install git composer unzip

Step 3: Configure the Database

  1. Secure the MariaDB Installation:
sudo mysql_secure_installation

Follow the prompts to set up the root password and secure your installation.

  1. Create a Database for BookStack:
sudo mysql -u root -p

Enter your root password, then run the following commands in the MariaDB prompt:

CREATE DATABASE bookstack;
    CREATE USER 'bookstackuser'@'localhost' IDENTIFIED BY 'yourpassword';
    GRANT ALL PRIVILEGES ON bookstack.* TO 'bookstackuser'@'localhost';
    FLUSH PRIVILEGES;
    EXIT;

Replace yourpassword with a secure password.

Step 4: Install BookStack

  1. Clone the BookStack Repository:
cd /var/www
sudo git clone https://github.com/BookStackApp/BookStack.git --branch release --single-branch bookstack
cd bookstack
  1. Install Composer Dependencies:
sudo composer install
  1. Set Up Environment Configuration:
sudo cp .env.example .env
sudo nano .env

Update the following lines with your database details:

DB_DATABASE=bookstack
DB_USERNAME=bookstackuser
DB_PASSWORD=yourpassword

Save and exit the file.

  1. Generate Application Key and Run Migrations:
sudo php artisan key:generate
sudo php artisan migrate

Step 5: Configure Apache

  1. Create Apache Configuration File:
sudo nano /etc/apache2/sites-available/bookstack.conf

Add the following content:

<VirtualHost *:80>
        ServerAdmin [email protected]
        DocumentRoot /var/www/bookstack/public
        ServerName your_domain_or_ip
    
        <Directory /var/www/bookstack/public>
            Options Indexes FollowSymLinks
            AllowOverride All
            Require all granted
        </Directory>
    
        ErrorLog ${APACHE_LOG_DIR}/bookstack_error.log
        CustomLog ${APACHE_LOG_DIR}/bookstack_access.log combined
</VirtualHost>

Replace your_domain_or_ip with your Raspberry Pi's IP address or domain name.

  1. Enable the BookStack Site and Rewrite Module:
sudo a2ensite bookstack
sudo a2enmod rewrite
sudo systemctl restart apache2

Step 6: Set File Permissions

Ensure the Apache user has the correct permissions to manage BookStack files.

sudo chown -R www-data:www-data /var/www/bookstack
sudo chmod -R 755 /var/www/bookstack

Step 7: Access BookStack

Open a web browser on your computer and navigate to http://your_domain_or_ip. You should see the BookStack setup page. Follow the instructions to create an admin account and complete the setup.

Conclusion

By following these steps, you can install and configure BookStack on your Raspberry Pi, providing a powerful and flexible documentation platform. Whether for personal use, project documentation, or team collaboration, BookStack offers an easy-to-use interface and robust features to manage your knowledge base efficiently. Enjoy your new self-hosted documentation platform!