BookStack is an open-source, self-hosted documentation platform designed for organizing and managing knowledge in a simple and user-friendly way. It’s an excellent choice for individuals and teams who want full control over their data and need a highly customizable solution for creating and sharing content. In this guide, we’ll cover everything from installing BookStack to configuring Nginx, managing logs, setting up backups, and leveraging its unique features.
Installing BookStack
📦 Docker/Docker Compose Setup
Docker is the easiest way to deploy BookStack. Below is a docker-compose.yml tailored for BookStack with support for persistent storage and database configuration.
version: '3.8'
services:
bookstack:
image: ghcr.io/linuxserver/bookstack:latest
container_name: bookstack
environment:
- PUID=1000
- PGID=1000
- APP_URL=http://yourdomain.com # Replace with your domain
- DB_HOST=bookstack_db
- DB_USER=bookstack
- DB_PASS=strongpassword
- DB_DATABASE=bookstack
volumes:
- ./bookstack/config:/config
ports:
- 8080:80
depends_on:
- bookstack_db
bookstack_db:
image: ghcr.io/linuxserver/mariadb:latest
container_name: bookstack_db
environment:
- MYSQL_ROOT_PASSWORD=rootpassword
- MYSQL_DATABASE=bookstack
- MYSQL_USER=bookstack
- MYSQL_PASSWORD=strongpassword
volumes:
- ./bookstack/db:/config
To deploy BookStack using Docker Compose:
mkdir ~/bookstack && cd ~/bookstack
## Save the docker-compose.yml file in this directory
nano docker-compose.yml
## Start the containers
docker-compose up -d
## Check the status of the containers
docker ps
Access BookStack in your browser at http://<your-server-ip>:8080.
🚀 Manual Installation
For users who prefer a manual setup, follow these steps to install BookStack on an Ubuntu server.
## Update system packages
sudo apt update && sudo apt upgrade -y
## Install dependencies
sudo apt install -y git unzip curl composer php-cli php-mbstring php-xml php-bcmath php-curl mariadb-server nginx
## Set up the database
sudo mysql -u root -p <<EOF
CREATE DATABASE bookstack;
CREATE USER 'bookstack'@'localhost' IDENTIFIED BY 'strongpassword';
GRANT ALL PRIVILEGES ON bookstack.* TO 'bookstack'@'localhost';
FLUSH PRIVILEGES;
EOF
## Clone the BookStack repository
cd /var/www
sudo git clone https://github.com/BookStackApp/BookStack.git --branch release --single-branch bookstack
## Set up permissions
sudo chown -R www-data:www-data /var/www/bookstack
cd bookstack
## Install PHP dependencies
composer install
## Set up the environment file
cp .env.example .env
nano .env # Update APP_URL and database credentials
## Run database migrations
php artisan migrate --force
## Start BookStack (via PHP's built-in server or configure Nginx as shown below)
php artisan serve --host=0.0.0.0 --port=8080
Visit http://your-server-ip:8080 to complete the setup.
Configuring Nginx as a Reverse Proxy
🌐 Nginx Configuration
Nginx can be configured as a reverse proxy to route traffic to BookStack. Here is a sample Nginx server block configuration.
server {
listen 80;
server_name yourdomain.com;
location / {
proxy_pass http://127.0.0.1:8080; # Update if using Docker
proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header X-Forwarded-Proto $scheme;
}
client_max_body_size 100M;
}
Save this configuration to /etc/nginx/sites-available/bookstack and enable it:
sudo ln -s /etc/nginx/sites-available/bookstack /etc/nginx/sites-enabled/
sudo nginx -t
sudo systemctl reload nginx
🔒 SSL/TLS Setup
Secure the site with a Let's Encrypt SSL certificate.
sudo apt install certbot python3-certbot-nginx
sudo certbot --nginx -d yourdomain.com
To automate SSL renewal:
sudo systemctl enable certbot.timer
🛠️ Testing and Reloading Nginx
After making changes to Nginx, test and reload the configuration:
sudo nginx -t
sudo systemctl reload nginx
Logging and Debugging BookStack
🗃️ Enabling Debug Logs
To enable debug logs, edit the .env file in your BookStack directory:
nano /var/www/bookstack/.env
## Set APP_DEBUG=true
Restart BookStack to apply changes:
php artisan serve --host=0.0.0.0 --port=8080
📄 Viewing Logs
For Docker deployments:
docker logs bookstack
For manual installations:
tail -f /var/www/bookstack/storage/logs/laravel.log
🛠️ Troubleshooting Common Issues
-
Database connection errors: Check
.envcredentials and ensure the database container/service is running. -
Permission issues: Verify file and directory ownership (
sudo chown -R www-data:www-data /var/www/bookstack).
📤 Exporting Logs
To forward logs to an external system like ELK Stack, you can use Filebeat or a similar tool to monitor laravel.log.
Backup and Restore
🗂️ File-Based Backups
Create a backup of BookStack files:
tar -czvf bookstack_files_$(date +%F).tar.gz /var/www/bookstack
🔄 Database Backups
Export the database:
mysqldump -u bookstack -p bookstack > bookstack_db_$(date +%F).sql
📅 Automated Backup Scripts
Schedule periodic backups using a cron job:
crontab -e
## Add the following line (adjust paths as necessary)
0 2 * * * /usr/bin/mysqldump -u bookstack -p'strongpassword' bookstack > /backups/bookstack_$(date +\%F).sql
Updating and Upgrading BookStack
⬆️ Updating Docker Images
To update BookStack when using Docker:
docker-compose pull
docker-compose down
docker-compose up -d
🛠️ Manual Updates
For manual installations, pull the latest changes from the repository:
cd /var/www/bookstack
sudo git pull origin release
composer install
php artisan migrate --force
🔍 Checking for Updates
Visit the BookStack GitHub repository to see the latest release.
Leveraging BookStack’s Unique Features
🔧 Enabling APIs
To use BookStack’s API, enable it in the .env file:
nano /var/www/bookstack/.env
## Add/modify the following:
APP_API=true
Test the API using curl:
curl -H "Authorization: Token yourapitoken" https://yourdomain.com/api/books
🌟 Advanced Configurations
Customize themes or add integrations by modifying the .env file and uploading assets to /var/www/bookstack/public.
Wrapping Up
With BookStack’s self-hosted solution, you gain full control over your documentation platform while benefiting from powerful features like API integrations, SSL security, and easy backups. By following this guide, you’ve set up, secured, and optimized BookStack for your use case. Start exploring its features and customize it to suit your team’s needs!
