Installing BookStack on a VPS: A

Backups and Maintenance

Regular backups are the cornerstone of any production system. BookStack stores data in a database and files (images, attachments) on disk. Maintenance includes software updates and monitoring.

1. What to Back Up

• BookStack Database: Contains all pages, books, chapters, users, and settings. This is the most important part.
• BookStack Files: Include uploaded images, attachments, and also the .env file (with sensitive data such as the application key and DB credentials).

2. Simple Auto-Backup Script

Let's create a simple script for backups. It is recommended not to store backups on the same server.

sudo nano /usr/local/bin/bookstack_backup.sh

Insert the following content, replacing ВАШ_НАДЕЖНЫЙ_ПАРОЛЬ_ДЛЯ_БД and bookstack_db with your values:

#!/bin/bash

# Configuration
DB_NAME="bookstack_db"
DB_USER="bookstack_user" # It's better to create a separate MySQL user just for backups with SELECT, LOCK TABLES privileges
DB_PASS="ВАШ_НАДЕЖНЫЙ_ПАРОЛЬ_ДЛЯ_БД"
BOOKSTACK_PATH="/var/www/bookstack"
BACKUP_DIR="/var/backups/bookstack"
DATE=$(date +%Y%m%d%H%M%S)
FILENAME_DB="${DB_NAME}_${DATE}.sql"
FILENAME_FILES="bookstack_files_${DATE}.tar.gz"

# Create backup directory if it doesn't exist
mkdir -p "${BACKUP_DIR}"

echo "Starting BookStack backup..."

# 1. Database Backup
echo "Backing up database..."
mysqldump --user="${DB_USER}" --password="${DB_PASS}" "${DB_NAME}" > "${BACKUP_DIR}/${FILENAME_DB}"
if [ $? -eq 0 ]; then
    echo "Database backup successfully created: ${FILENAME_DB}"
else
    echo "Error creating database backup."
    exit 1
fi

# 2. BookStack Files Backup (excluding cache and logs)
echo "Backing up BookStack files..."
tar -czf "${BACKUP_DIR}/${FILENAME_FILES}" -C "${BOOKSTACK_PATH}" \
    --exclude='storage/uploads/images/*' \
    --exclude='storage/uploads/files/*' \
    --exclude='storage/logs/*' \
    --exclude='bootstrap/cache/*' \
    --exclude='vendor/*' \
    .
# Additionally, save only .env and uploads separately for easy restoration
cp "${BOOKSTACK_PATH}/.env" "${BACKUP_DIR}/bookstack_env_${DATE}.env"
tar -czf "${BACKUP_DIR}/bookstack_uploads_images_${DATE}.tar.gz" -C "${BOOKSTACK_PATH}/storage/uploads" images
tar -czf "${BACKUP_DIR}/bookstack_uploads_files_${DATE}.tar.gz" -C "${BOOKSTACK_PATH}/storage/uploads" files

if [ $? -eq 0 ]; then
    echo "BookStack files backup successfully created: ${FILENAME_FILES}"
else
    echo "Error creating BookStack files backup."
    exit 1
fi

# 3. Deleting old backups (e.g., older than 7 days)
echo "Deleting old backups..."
find "${BACKUP_DIR}" -type f -name "*.sql" -mtime +7 -delete
find "${BACKUP_DIR}" -type f -name "*.tar.gz" -mtime +7 -delete
find "${BACKUP_DIR}" -type f -name "*.env" -mtime +7 -delete

echo "Backup completed."

Save the file and make it executable:

sudo chmod +x /usr/local/bin/bookstack_backup.sh

3. Automating Backups with Cron

Let's add the script to the Cron scheduler for daily execution.

sudo crontab -e

Choose a text editor (if prompted) and add the following line to the end of the file to perform a backup every day at 3:00 AM:

0 3 * * * /usr/local/bin/bookstack_backup.sh >> /var/log/bookstack_backup.log 2>&1

Save and exit. Now backups will be created automatically.

4. Where to Store Backups

Never store all backups only on the same server as the main service! If the server fails, you will lose everything.

• External S3-compatible storage: Amazon S3, DigitalOcean Spaces, Backblaze B2. This is a reliable and relatively inexpensive option. You can use utilities like s3cmd or rclone for automatic synchronization.
• Separate VPS: Rent a small, cheap VPS exclusively for storing backups and synchronize them there via SFTP/RSYNC.
• Local Network Drive (NAS): If you have your own infrastructure.

For example, to send backups to S3, you can add the command s3cmd put "${BACKUP_DIR}/${FILENAME_DB}" s3://your-s3-bucket/bookstack/ to the bookstack_backup.sh script after creating the archives (this will require installing and configuring s3cmd).

5. Updates: rolling vs maintenance window

Regular updates are critically important for security and new features.

• System Updates (OS, PHP, MySQL):
  • Rolling (continuous): For non-critical security patches, automatic updates can be configured (e.g., using unattended-upgrades).
  • Maintenance Window: For major updates to PHP, MySQL, or the Linux kernel, it is recommended to plan a maintenance window, as these may require a server reboot or lead to temporary service unavailability. Test updates on a staging server if possible.

  
  sudo apt update && sudo apt upgrade -y # System update
  

• BookStack Updates:

  BookStack is updated via Git and Composer. It is recommended to perform these during a maintenance window.

  
  cd /var/www/bookstack
  git pull # Download latest changes from the repository
  composer install --no-dev # Update dependencies
  php artisan migrate --force # Run database migrations (if any)
  php artisan cache:clear # Clear BookStack cache
  php artisan view:clear # Clear view cache
  sudo chown -R www-data:www-data /var/www/bookstack # Ensure permissions are correct after pull
  sudo chmod -R 775 /var/www/bookstack/storage /var/www/bookstack/bootstrap/cache
  sudo systemctl reload php8.3-fpm # Restart PHP-FPM
  sudo systemctl reload caddy # Restart Caddy
  

  Always check the official BookStack documentation before updating, as the process may change.

Troubleshooting + FAQ

My BookStack is not working, I see a 500 error or a blank page. What should I do?

A 500 error (Internal Server Error) usually indicates a problem with PHP or the application. First, check the logs:

• Caddy Logs: sudo tail -f /var/log/caddy/access.log and sudo journalctl -u caddy -f. Look for errors related to PHP proxying.
• PHP-FPM Logs: sudo tail -f /var/log/php8.3-fpm.log (or the corresponding PHP version).
• BookStack Logs: sudo tail -f /var/www/bookstack/storage/logs/laravel.log. This is the most important log for debugging BookStack's own issues.

Common causes: incorrect file/directory permissions (especially storage and bootstrap/cache), errors in the .env file (incorrect DB credentials, wrong APP_URL), missing PHP extensions, database connection issues.

What is the minimum VPS configuration suitable for BookStack?

For small personal use or a team of 2-3 people with not a very large amount of data, a VPS with 1-2 vCPU, 2 GB of RAM, and a 40 GB SSD disk will be minimally suitable. This is sufficient for stable operation of Ubuntu 24.04 LTS, PHP 8.3/8.4, MySQL 8.0, and Caddy with BookStack. It is important that the disk is SSD for good database performance.

What to choose — VPS or dedicated for this task?

For most BookStack use cases (personal wiki, knowledge base for a small or medium team of up to 30-50 people), a VPS is the optimal choice. It offers sufficient performance, flexibility, and is significantly lower in cost. A dedicated server should be considered if you have a very large team (hundreds of users), a huge amount of data, critical performance requirements without any compromises, or if you plan to host many other resource-intensive applications on the same server.

I changed the domain name. What needs to be updated?

If you have changed the domain name, you need to update at least two places:

1. BookStack .env file: Change the APP_URL value to the new domain name (e.g., APP_URL=https://new-domain.com).
2. Caddyfile: Edit /etc/caddy/Caddyfile and replace the old domain name with the new one in the first line (e.g., new-domain.com { ... }).

How to update BookStack to a new version?

The BookStack update process usually includes: navigating to the BookStack directory (cd /var/www/bookstack), pulling the latest changes from Git (git pull), updating PHP dependencies via Composer (composer install --no-dev), running database migrations (php artisan migrate --force), and clearing the BookStack cache (php artisan cache:clear && php artisan view:clear). It is always recommended to read the official update instructions for a specific BookStack version, as there may be specific steps.

BookStack returns "Access Denied" error when trying to connect to MySQL.

This error means that BookStack cannot connect to the MySQL database with the provided credentials. Check the following:

• .env file: Make sure that DB_USERNAME, DB_PASSWORD, and DB_DATABASE in the /var/www/bookstack/.env file exactly match those you created in MySQL.
• MySQL User: Make sure that the user bookstack_user exists in MySQL and has the correct privileges for the bookstack_db database. You can check this by logging into MySQL as root and executing SELECT user, host FROM mysql.user; and SHOW GRANTS FOR 'bookstack_user'@'localhost';.
• MySQL Service: Check that the MySQL service is running: sudo systemctl status mysql.

Conclusions and Next Steps

Congratulations! You have successfully installed and configured BookStack on your VPS, creating a reliable and controlled knowledge management platform. Now you have a powerful tool for organizing information, whether it's personal notes, project documentation, or an extensive knowledge base for your team. You have gained full control over your data and infrastructure, ensuring privacy and security.

Where to go next?

• User and Role Configuration: In BookStack, you can create users, groups, and assign them various access rights to books, chapters, and pages. Start by creating accounts for your team and configuring appropriate permissions.
• Appearance Customization: BookStack allows you to change the logo, color scheme, and add custom CSS to brand your wiki according to your style.
• Integration with External Services: Consider setting up Single Sign-On (SSO) via LDAP, SAML2, or social providers, if relevant for your team.
• Server Monitoring: Install monitoring systems (e.g., Prometheus + Grafana or Zabbix) to track CPU, RAM, disk usage, and service status to promptly react to potential issues.