BookStack Deployment & Usage Guide

1. Prerequisites

Before installing BookStack, ensure your system meets these requirements:

Server Requirements:

PHP 8.0.2 or higher (with extensions: ctype, curl, dom, fileinfo, gd, json, mbstring, openssl, pdo, session, tokenizer, xml, zip)
MySQL 5.7+ or MariaDB 10.2+
Web server (Apache, Nginx, or similar)
Composer (PHP dependency manager)
Node.js & NPM (for development)

Recommended:

1GB+ RAM
2GB+ disk space
SSL certificate for production use

2. Installation

Quick Install (Production)

# Download the latest release
wget https://github.com/BookStackApp/BookStack/archive/refs/tags/v<version>.tar.gz
tar -xzf v<version>.tar.gz
cd BookStack-<version>

# Install PHP dependencies
composer install --no-dev

# Set proper permissions
chown -R www-data:www-data /path/to/bookstack
chmod -R 755 /path/to/bookstack

Development Installation

# Clone the repository
git clone https://github.com/BookStackApp/BookStack.git
cd BookStack

# Install PHP dependencies
composer install

# Install frontend dependencies (if modifying assets)
npm install

# Build frontend assets (development)
npm run dev

3. Configuration

Environment Setup

Copy the example environment file and configure your settings:

cp .env.example .env

Edit .env with your configuration:

# Basic Application Settings
APP_NAME="BookStack"
APP_ENV=production
APP_DEBUG=false
APP_KEY=  # Generate with: php artisan key:generate
APP_URL=https://your-domain.com

# Database Configuration
DB_HOST=localhost
DB_PORT=3306
DB_DATABASE=bookstack
DB_USERNAME=bookstack
DB_PASSWORD=your_secure_password

# Mail Configuration (for notifications)
MAIL_MAILER=smtp
MAIL_HOST=mailhog
MAIL_PORT=1025
MAIL_USERNAME=null
MAIL_PASSWORD=null
MAIL_FROM_ADDRESS=null
MAIL_FROM_NAME="${APP_NAME}"

# Cache & Session
CACHE_DRIVER=file
SESSION_DRIVER=file
SESSION_LIFETIME=120

# Security Features
APP_PUBLIC=false  # Set to true to allow public access
APP_EDITOR=wysiwyg  # Options: wysiwyg or markdown
APP_SECURE_IMAGES=false  # Enable for harder-to-guess image URLs

Database Setup

# Create database and user
mysql -u root -p
CREATE DATABASE bookstack CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
CREATE USER 'bookstack'@'localhost' IDENTIFIED BY 'your_password';
GRANT ALL ON bookstack.* TO 'bookstack'@'localhost';
FLUSH PRIVILEGICES;
EXIT;

# Run database migrations
php artisan migrate

# Generate application key
php artisan key:generate

4. Build & Run

Development Mode

# Start local development server
php artisan serve

# Watch for asset changes (separate terminal)
npm run watch

# Access at: http://localhost:8000

Production Build

# Build production assets
npm run production

# Clear and cache configuration
php artisan config:clear
php artisan cache:clear
php artisan view:clear
php artisan config:cache
php artisan route:cache
php artisan view:cache

Web Server Configuration

Nginx Configuration:

server {
    listen 80;
    server_name your-domain.com;
    root /var/www/bookstack/public;
    index index.php;

    location / {
        try_files $uri $uri/ /index.php?$query_string;
    }

    location ~ \.php$ {
        include snippets/fastcgi-php.conf;
        fastcgi_pass unix:/var/run/php/php8.1-fpm.sock;
        fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name;
        include fastcgi_params;
    }

    location ~ /\.ht {
        deny all;
    }
}

Apache Configuration: Ensure the .htaccess file in the public directory is properly configured and mod_rewrite is enabled.

5. Deployment

Recommended Platforms

Self-Hosted Options:

Traditional VPS (DigitalOcean, Linode, AWS EC2)
- Full control over configuration
- Requires manual setup and maintenance

Docker Deployment

# Using official Docker image
docker run -d \
  --name bookstack \
  -p 8080:80 \
  -e DB_HOST=database_host \
  -e DB_DATABASE=bookstack \
  -e DB_USERNAME=bookstack \
  -e DB_PASSWORD=your_password \
  solidnerd/bookstack:latest

Managed PHP Hosting (Laravel Forge, Ploi.io)
- Automated deployment
- Built-in SSL, backups, and monitoring

Cloud-Native Options:

AWS Elastic Beanstalk (PHP platform)
Google App Engine (PHP runtime)
Azure App Service (PHP stack)

Deployment Checklist

6. Troubleshooting

Common Issues & Solutions

1. "No application encryption key has been specified."

# Generate application key
php artisan key:generate

2. Database Connection Errors

Verify database credentials in .env
Ensure database user has proper permissions
Check if MySQL/MariaDB is running: sudo systemctl status mysql

3. Permission Issues

# Set correct ownership (adjust user/group as needed)
sudo chown -R www-data:www-data /path/to/bookstack
sudo chmod -R 755 /path/to/bookstack
sudo chmod -R 775 /path/to/bookstack/storage
sudo chmod -R 775 /path/to/bookstack/bootstrap/cache

4. 404 Errors on Routes

Ensure web server rewrite rules are properly configured
For Apache: a2enmod rewrite and restart Apache
Check that the public/.htaccess file exists

5. Image Upload Issues

Check storage directory permissions
Verify PHP file_uploads and upload_max_filesize settings
Ensure GD or Imagick extension is installed

6. Slow Performance

Enable opcache in PHP configuration
Configure database indexing
Use Redis for cache/sessions (update CACHE_DRIVER and SESSION_DRIVER in .env)
Enable CDN for static assets

7. Public Access Not Working

Set APP_PUBLIC=true in .env
Configure guest user permissions in Settings → Users
Check role permissions for "Public" role

Debug Mode

For troubleshooting, temporarily enable debug mode in .env:

APP_DEBUG=true
APP_ENV=local

Warning: Never run with APP_DEBUG=true in production due to security risks.

Logs

Check application logs for detailed error information:

# Laravel logs
tail -f storage/logs/laravel.log

# Web server logs
tail -f /var/log/nginx/error.log
tail -f /var/log/apache2/error.log

Maintenance Commands

# Clear all caches
php artisan cache:clear
php artisan config:clear
php artisan view:clear

# Re-cache for production
php artisan config:cache
php artisan route:cache
php artisan view:cache

# Check system health
php artisan bookstack:check

How to Deploy & Use BookStack