Installing BookStack on the Raspberry Pi
![Ben](https://fleetstack.s3.eu-west-2.amazonaws.com/assets/blog/benjislab.webp)
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
- Download Raspberry Pi OS:
Download the latest version of Raspberry Pi OS Lite from the official Raspberry Pi website.
- 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.
- 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.
- 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.
- 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
- Install Git and Composer:
sudo apt install git composer unzip
Step 3: Configure the Database
- Secure the MariaDB Installation:
sudo mysql_secure_installation
Follow the prompts to set up the root password and secure your installation.
- 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
- Clone the BookStack Repository:
cd /var/www
sudo git clone https://github.com/BookStackApp/BookStack.git --branch release --single-branch bookstack
cd bookstack
- Install Composer Dependencies:
sudo composer install
- 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.
- Generate Application Key and Run Migrations:
sudo php artisan key:generate
sudo php artisan migrate
Step 5: Configure Apache
- 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.
- 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!