Every growing team eventually hits the same wall: scattered documentation across Google Docs, Confluence subscriptions that scale with headcount, and tribal knowledge locked inside individual brains. BookStack is an open-source, self-hosted documentation platform that solves all three problems. Built on Laravel and MySQL, it provides a clean, hierarchical wiki system — shelves, books, chapters, and pages — that your entire team can use without per-user licensing fees.

Self-hosting BookStack on an Ubuntu VPS gives you complete control over your documentation infrastructure. Your content stays on your servers, your search indexes remain private, and your costs stay fixed regardless of whether you have five users or five hundred. This guide walks through a full production deployment: installation, Nginx with SSL, user management, SSO integration, search tuning, and backup automation.

MassiveGRID Ubuntu VPS includes: Ubuntu 24.04 LTS pre-installed · Proxmox HA cluster with automatic failover · Ceph 3x replicated NVMe storage · Independent CPU/RAM/storage scaling · 12 Tbps DDoS protection · 4 global datacenter locations · 100% uptime SLA · 24/7 human support rated 9.5/10

Deploy a self-managed VPS — from $1.99/mo
Need dedicated resources? — from $19.80/mo
Want fully managed hosting? — we handle everything

Why Self-Host Your Documentation Platform

Cloud-hosted documentation tools like Confluence and Notion charge per user, per month. At scale, this becomes a serious line item — Confluence Standard costs $6.05 per user monthly, meaning a 100-person team pays over $7,200 annually just to write internal docs. BookStack eliminates that entirely. Once deployed, you pay only for the VPS resources, regardless of how many people access the system.

Beyond cost, self-hosting gives you data sovereignty. Sensitive internal documentation — security procedures, architecture decisions, employee handbooks, API credentials — never leaves your infrastructure. You control access at the network level, decide where data is stored geographically, and maintain full audit trails without relying on a third party's compliance certifications.

Self-hosted platforms also give you uptime independence. Your documentation stays available even if a SaaS provider experiences outages, changes their pricing model, or sunsets their product. Your knowledge base runs on infrastructure you control.

Compliance is another critical factor. Industries like healthcare, finance, and government often require documentation systems to meet specific data handling standards — HIPAA, SOC 2, GDPR, or FedRAMP. Self-hosting BookStack on infrastructure you manage allows you to implement the exact controls your compliance framework requires, without depending on a vendor's attestation timeline or trusting their internal security practices.

BookStack vs Confluence vs Wiki.js vs Notion

Choosing the right documentation platform depends on your team's technical capacity and organizational needs. Here is how BookStack compares to the most common alternatives:

For most teams that want a self-hosted wiki with minimal operational overhead, BookStack is the strongest choice. Its shelf → book → chapter → page hierarchy maps naturally to how organizations structure documentation.

Prerequisites: Ubuntu VPS with LEMP Stack

BookStack requires PHP 8.1+, MySQL 5.7+ (or MariaDB 10.3+), and a web server. The simplest foundation is a LEMP stack on Ubuntu 24.04 LTS.

Before proceeding, ensure you have a working LEMP installation. If you need to set one up, follow our guide to installing the LEMP stack on Ubuntu VPS. You should have Nginx, MySQL (or MariaDB), and PHP 8.3 with the required extensions installed and running.

Verify your environment meets BookStack's requirements:

php -v
# Should show PHP 8.1 or higher

mysql --version
# Should show MySQL 5.7+ or MariaDB 10.3+

nginx -v
# Should show nginx version

Install the additional PHP extensions BookStack requires:

sudo apt install php8.3-gd php8.3-mysql php8.3-xml php8.3-mbstring php8.3-curl php8.3-zip php8.3-ldap php8.3-tidy -y
sudo systemctl restart php8.3-fpm

Create a dedicated MySQL database and user for BookStack:

sudo mysql -u root -p

CREATE DATABASE bookstack CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
CREATE USER 'bookstack'@'localhost' IDENTIFIED BY 'your_secure_password_here';
GRANT ALL PRIVILEGES ON bookstack.* TO 'bookstack'@'localhost';
FLUSH PRIVILEGES;
EXIT;

Installing BookStack with Composer

BookStack is a Laravel application distributed via Git and managed with Composer. Clone the repository and install dependencies:

cd /var/www
sudo git clone https://github.com/BookStackApp/BookStack.git --branch release --single-branch bookstack
cd bookstack
sudo composer install --no-dev

Copy the example environment file and generate an application key:

sudo cp .env.example .env
sudo php artisan key:generate

Edit the .env file to configure your database connection and application URL:

sudo nano .env

Set the following values:

APP_URL=https://wiki.yourdomain.com
DB_HOST=localhost
DB_DATABASE=bookstack
DB_USERNAME=bookstack
DB_PASSWORD=your_secure_password_here

Run the database migrations to create all required tables:

sudo php artisan migrate --force

Set proper file ownership so the web server can read and write to storage directories:

sudo chown -R www-data:www-data /var/www/bookstack
sudo chmod -R 755 /var/www/bookstack/storage
sudo chmod -R 755 /var/www/bookstack/bootstrap/cache
sudo chmod -R 755 /var/www/bookstack/public/uploads

Configuring Nginx with SSL

BookStack needs an Nginx virtual host that handles PHP-FPM proxying and serves static assets. For detailed guidance on Nginx reverse proxy configuration and SSL certificate management, see our Nginx reverse proxy setup guide.

Create the Nginx server block:

sudo nano /etc/nginx/sites-available/bookstack

Add the following configuration:

server {
    listen 80;
    server_name wiki.yourdomain.com;
    return 301 https://$host$request_uri;
}

server {
    listen 443 ssl http2;
    server_name wiki.yourdomain.com;

    ssl_certificate /etc/letsencrypt/live/wiki.yourdomain.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/wiki.yourdomain.com/privkey.pem;

    root /var/www/bookstack/public;
    index index.php;

    client_max_body_size 50M;

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

    location ~ \.php$ {
        include fastcgi_params;
        fastcgi_pass unix:/run/php/php8.3-fpm.sock;
        fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name;
        fastcgi_read_timeout 300;
    }

    location ~* \.(js|css|png|jpg|jpeg|gif|ico|svg|woff|woff2)$ {
        expires 30d;
        add_header Cache-Control "public, immutable";
    }
}

Enable the site and test the configuration:

sudo ln -s /etc/nginx/sites-available/bookstack /etc/nginx/sites-enabled/
sudo nginx -t
sudo systemctl reload nginx

If you have not already obtained an SSL certificate, use Certbot:

sudo certbot --nginx -d wiki.yourdomain.com

Initial Setup: Shelves, Books, and Chapters

Navigate to your BookStack URL and log in with the default credentials: admin@admin.com / password. Change these immediately after first login.

BookStack organizes content in a four-level hierarchy:

A practical starting structure for most teams:

Engineering (Shelf)
├── Architecture Decisions (Book)
│   ├── Infrastructure (Chapter)
│   │   ├── Database Selection
│   │   └── Cloud Provider Evaluation
│   └── Application (Chapter)
│       ├── Authentication Strategy
│       └── API Design Standards
├── Runbooks (Book)
│   ├── Deployment Procedures
│   └── Incident Response
└── Developer Onboarding (Book)

Operations (Shelf)
├── Infrastructure Documentation (Book)
└── Monitoring & Alerting (Book)

Company (Shelf)
├── Employee Handbook (Book)
└── Policies & Procedures (Book)

BookStack supports both a WYSIWYG editor and a Markdown editor. You can set the default per user or globally in the .env file with APP_EDITOR=markdown. The WYSIWYG editor is recommended for teams with mixed technical backgrounds, as it provides a familiar word-processor experience with drag-and-drop image embedding, table creation, and rich formatting — no Markdown syntax required.

Templates are another powerful organizational feature. Create page templates for recurring document types — meeting notes, incident reports, architecture decision records — and your team can generate consistently structured pages with a single click. This reduces friction for contributors and keeps your knowledge base uniform.

User Management and Role-Based Permissions

BookStack includes a granular role-based permission system. Out of the box, it provides Admin, Editor, and Viewer roles. You can create custom roles with fine-grained permissions at every level of the content hierarchy.

To create a custom role, go to Settings → Roles → Create New Role. Assign permissions for each action type:

Permissions cascade downward but can be overridden at any level. For example, you can grant a role view access to an entire shelf but restrict a specific book within that shelf to only certain roles. This is managed through the Permissions tab on each shelf, book, chapter, or page.

For team-based access, create roles that map to your organizational structure — "Engineering Team", "Marketing Team", "Leadership" — and assign content permissions accordingly. This keeps documentation organized and prevents information sprawl.

BookStack also maintains a full audit log of all user actions — page views, edits, deletions, permission changes, and login events. Access this under Settings → Audit Log to track who changed what and when. For regulated industries, this built-in audit trail satisfies many compliance requirements without additional tooling.

SSO with SAML/OIDC via Authentik

For teams with more than a handful of users, managing BookStack accounts manually becomes impractical. Integrating with an identity provider via SAML or OpenID Connect centralizes authentication and enables single sign-on across all your self-hosted applications.

Authentik is an excellent self-hosted identity provider that pairs well with BookStack. If you do not have Authentik running yet, follow our guide to self-hosting Authentik on Ubuntu VPS.

To configure OIDC authentication, add the following to your BookStack .env file:

AUTH_METHOD=oidc
AUTH_AUTO_INITIATE=false

OIDC_NAME=Authentik
OIDC_DISPLAY_NAME_CLAIMS=name
OIDC_CLIENT_ID=your_client_id
OIDC_CLIENT_SECRET=your_client_secret
OIDC_ISSUER=https://auth.yourdomain.com/application/o/bookstack/
OIDC_ISSUER_DISCOVER=true
OIDC_USER_TO_GROUPS=true
OIDC_GROUPS_CLAIM=groups
OIDC_REMOVE_FROM_GROUPS=false

In Authentik, create a new OAuth2/OIDC provider with the redirect URI set to https://wiki.yourdomain.com/oidc/callback. Map Authentik groups to BookStack roles for automatic role assignment — when a user logs in, they receive permissions based on their group membership in your identity provider.

Setting OIDC_USER_TO_GROUPS=true enables automatic group synchronization. Users added to the "Engineering" group in Authentik will automatically receive the corresponding BookStack role and all associated content permissions.

Customization and Branding

BookStack allows extensive visual customization without modifying source code. Under Settings → Customization, you can:

For deeper CSS customization, use the custom head content field to inject a <style> block. This survives BookStack updates since it is stored in the database rather than in modified theme files.

<style>
  :root {
    --color-primary: #1a56db;
    --color-primary-light: #3b82f6;
  }
  .header { background-color: #0f172a; }
</style>

Full-Text Search and MySQL Performance Tuning

BookStack uses MySQL full-text indexes for its search functionality. As your knowledge base grows beyond a few hundred pages, search performance depends heavily on MySQL configuration. For comprehensive database optimization, refer to our MySQL and MariaDB performance tuning guide.

Key MySQL settings that impact BookStack search performance:

# /etc/mysql/mysql.conf.d/mysqld.cnf

[mysqld]
# InnoDB buffer pool — set to 50-70% of available RAM for dedicated DB servers
innodb_buffer_pool_size = 512M

# Full-text search minimum word length (default is 4, lower to 3 for better results)
innodb_ft_min_token_size = 3

# Query cache for repeated searches
innodb_ft_result_cache_limit = 2000000000

# Sort buffer for search result ordering
sort_buffer_size = 4M

After changing innodb_ft_min_token_size, rebuild the full-text indexes:

sudo mysql -u root -p -e "USE bookstack; OPTIMIZE TABLE pages; OPTIMIZE TABLE search_terms;"
sudo systemctl restart mysql

BookStack also supports advanced search syntax that your team should know about. Use exact phrase matching with quotes, tag filters with [tag:value], and scope searches to specific books or shelves. As your knowledge base grows, these operators become essential for finding the right page among thousands.

For knowledge bases with over 1,000 pages handling concurrent full-text search queries, a Dedicated VPS with guaranteed I/O performance ensures search remains responsive even under load. Shared storage can introduce latency spikes during heavy index operations that degrade the search experience for everyone on the team.

File Upload and Storage Configuration

BookStack stores uploaded images and file attachments in the storage/uploads directory by default. For production deployments, plan your storage allocation based on expected usage patterns.

Configure upload limits in your .env file:

# Maximum file upload size in MB
FILE_UPLOAD_SIZE_LIMIT=50

Ensure your PHP and Nginx configurations match this limit:

# /etc/php/8.3/fpm/php.ini
upload_max_filesize = 50M
post_max_size = 55M
memory_limit = 256M

# Nginx server block (already set above)
client_max_body_size 50M;

For teams that upload large diagrams, screenshots, and file attachments regularly, monitor your storage usage:

du -sh /var/www/bookstack/storage/uploads/
du -sh /var/www/bookstack/public/uploads/

If storage needs grow, MassiveGRID VPS instances allow independent storage scaling — increase NVMe allocation without changing CPU or RAM, so you only pay for the resources you actually need.

Automated Backups

A documentation platform is only as reliable as its backup strategy. BookStack data lives in two places: the MySQL database and the filesystem (uploads and configuration). Both must be backed up together for a consistent restore.

Create a backup script at /opt/scripts/backup-bookstack.sh:

#!/bin/bash
BACKUP_DIR="/opt/backups/bookstack"
TIMESTAMP=$(date +%Y%m%d_%H%M%S)
mkdir -p "$BACKUP_DIR"

# Database backup
mysqldump -u bookstack -p'your_secure_password_here' bookstack | gzip > "$BACKUP_DIR/db_$TIMESTAMP.sql.gz"

# File backup (uploads, config, themes)
tar czf "$BACKUP_DIR/files_$TIMESTAMP.tar.gz" \
  /var/www/bookstack/.env \
  /var/www/bookstack/storage/uploads \
  /var/www/bookstack/public/uploads

# Retain last 30 days of backups
find "$BACKUP_DIR" -name "*.gz" -mtime +30 -delete

echo "BookStack backup completed: $TIMESTAMP"

Schedule it with cron for daily execution:

sudo chmod +x /opt/scripts/backup-bookstack.sh
sudo crontab -e
# Add: 0 2 * * * /opt/scripts/backup-bookstack.sh >> /var/log/bookstack-backup.log 2>&1

For comprehensive backup strategies including off-site replication and encrypted remote storage, see our guide to automating backups on Ubuntu VPS.

API Integration and Automation

BookStack provides a full REST API that enables programmatic content management. This is invaluable for integrating your knowledge base with CI/CD pipelines, chatbots, or other internal tools.

Generate an API token under your user profile in Settings → API Tokens. Each token has a Token ID and Token Secret used for authentication:

# List all books
curl -s -H "Authorization: Token YOUR_TOKEN_ID:YOUR_TOKEN_SECRET" \
  https://wiki.yourdomain.com/api/books | jq '.data[].name'

# Create a new page in a specific book
curl -X POST \
  -H "Authorization: Token YOUR_TOKEN_ID:YOUR_TOKEN_SECRET" \
  -H "Content-Type: application/json" \
  -d '{
    "book_id": 1,
    "name": "Deployment Log - 2026-03-04",
    "html": "<p>Deployed version 2.4.1 to production.</p>"
  }' \
  https://wiki.yourdomain.com/api/pages

# Search across all content
curl -s -H "Authorization: Token YOUR_TOKEN_ID:YOUR_TOKEN_SECRET" \
  "https://wiki.yourdomain.com/api/search?query=deployment+procedures" | jq '.data[].name'

Common API automation use cases include:

Scale Your Knowledge Base Without Per-User Costs

The fundamental advantage of self-hosting BookStack is that your costs are tied to infrastructure, not headcount. A MassiveGRID VPS with 2 vCPUs and 2 GB RAM comfortably serves BookStack for teams of up to 50 concurrent users. As your organization grows, scale CPU and RAM independently — there is no license to renegotiate, no sales call to schedule, no per-seat fee increase to budget for.

With Ceph 3x replicated NVMe storage, your documentation data is protected against disk failures automatically. The Proxmox HA cluster ensures your wiki stays online even during hardware maintenance. Combined with 12 Tbps DDoS protection, your internal knowledge base is more resilient than most SaaS alternatives.

Prefer Managed Hosting for Your Knowledge Infrastructure?

If your team wants the benefits of self-hosted BookStack without the operational overhead of managing servers, MySQL tuning, backups, and security updates, MassiveGRID's fully managed hosting handles everything. We manage the infrastructure — OS updates, database optimization, backup verification, SSL renewals, and 24/7 monitoring — so your team can focus on writing documentation rather than maintaining the platform that hosts it.

Whether self-managed or fully managed, your knowledge base runs on enterprise-grade infrastructure with a 100% uptime SLA and support rated 9.5 out of 10 by real customers.