BookStack: The Developer-Friendly Documentation Wiki with Markdown Support — 2026 Setup & Review

{{< resource-info >}}

Introduction: The Documentation Mess Every Team Faces #

Your team’s documentation is scattered. Some of it lives in Google Docs that nobody can find. Some of it sits in a Notion workspace that your manager set up six months ago and abandoned. API docs are in README files, runbooks are in Confluence, and onboarding notes are in someone’s personal notes app. This is the universal documentation mess.

Dan Brown built BookStack to solve exactly this problem. First released in July 2015 as “Oxbow” and renamed eleven days later, BookStack has grown to 18,700+ GitHub stars and a community of over 186 direct contributors as of early 2026. In March 2026, the project hit v26.03 with a new theme module system, enhanced logical theme events for page content customization, and improved security filtering. The project migrated its canonical repository to Codeberg in early 2026, though a mirror remains on GitHub.

What makes BookStack different from the dozens of other wiki tools? Structure. Instead of the flat page-and-tag model that most wikis use, BookStack organizes documentation the way a physical library does — shelves contain books, books contain chapters, and chapters contain pages. This opinionated hierarchy forces teams to think about where information belongs, which is exactly why teams either love it or decide it is not for them.

This guide covers everything you need to get BookStack running in production: Docker deployment in under 5 minutes, configuration for your team, real benchmarks, honest limitations, and how it stacks up against Wiki.js, DokuWiki, MediaWiki, and Outline.

What Is BookStack? A One-Sentence Definition #

BookStack is a free, open-source, MIT-licensed documentation wiki built with PHP on Laravel that uses a book/chapter/page hierarchy to organize internal knowledge bases, runbooks, SOPs, and team documentation — fully self-hosted with no per-seat pricing.

How BookStack Works: Architecture & Core Concepts #

BookStack runs on a classic PHP/LAMP stack, which makes it predictable for anyone who has deployed a PHP application before. The architecture is straightforward:

The defining architectural decision is the content hierarchy. Unlike Notion (free-form pages) or Confluence (spaces + pages), BookStack enforces a Shelf → Book → Chapter → Page structure. When you create content, you must decide where it lives in that hierarchy. This reduces the “where do I put this?” friction that kills most wiki adoptions.

Shelf — Top-level container, typically maps to a department or major project area. Book — Major documentation area, like “Engineering Runbooks” or “HR Policies”. Chapter — Subdivision within a book, like “Database Procedures” or “Onboarding”. Page — The actual content unit, with full WYSIWYG or Markdown editing.

BookStack uses a role-based permission system. You define roles (like “Editor”, “Viewer”, “Admin”) and assign them permissions at the global level. Content visibility can be restricted per-book or per-shelf. The v26.03 release added enhanced content filtering using an allow-list approach via HTML Purifier, addressing security concerns where malicious page content could manipulate the DOM.

Installation & Setup: From Zero to Running in 5 Minutes #

The fastest way to run BookStack is with Docker Compose. You need a server with 2GB RAM minimum, 4GB recommended for teams over 50 users. A DigitalOcean Droplet with 2 vCPUs and 4GB RAM ($24/month) handles most small-to-medium teams comfortably.

Step 1: Create the Docker Compose file #

version: '3.8'

services:
  bookstack:
    image: lscr.io/linuxserver/bookstack:v26.03.4
    container_name: bookstack
    environment:
      - PUID=1000
      - PGID=1000
      - APP_URL=https://docs.yourdomain.com
      - DB_HOST=bookstack_db
      - DB_PORT=3306
      - DB_USER=bookstack
      - DB_PASS=your_secure_db_password
      - DB_DATABASE=bookstackdb
    volumes:
      - ./bookstack_app_data:/config
    ports:
      - 6875:80
    restart: unless-stopped
    depends_on:
      - bookstack_db

  bookstack_db:
    image: lscr.io/linuxserver/mariadb:10.11
    container_name: bookstack_db
    environment:
      - PUID=1000
      - PGID=1000
      - MYSQL_ROOT_PASSWORD=your_secure_root_password
      - TZ=UTC
      - MYSQL_DATABASE=bookstackdb
      - MYSQL_USER=bookstack
      - MYSQL_PASSWORD=your_secure_db_password
    volumes:
      - ./bookstack_db_data:/config
    restart: unless-stopped

This compose file defines two services: the BookStack application on port 6875 and a MariaDB database for persistence.

Step 2: Launch the stack #

# Create data directories
mkdir -p bookstack_app_data bookstack_db_data

# Start both containers
docker compose up -d

# Wait for database initialization (30-60 seconds on first run)
sleep 45

# Check logs to confirm startup
docker logs bookstack

You should see Laravel bootstrapping messages followed by NOTICE: ready to handle connections from PHP-FPM. If the database connection fails, check that the DB_HOST matches the service name bookstack_db and the credentials align.

Step 3: Access and configure #

# Default credentials on first boot
# Username: admin@admin.com
# Password: password

Navigate to http://your-server-ip:6875 and log in. Immediately change the admin password under Settings → Users. Then configure your APP_URL to use HTTPS — BookStack generates absolute URLs in email notifications and exports, so getting the APP_URL right from the start prevents broken links later.

Step 4: Nginx reverse proxy with SSL #

# /etc/nginx/sites-available/bookstack
server {
    listen 443 ssl http2;
    server_name docs.yourdomain.com;

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

    location / {
        proxy_pass http://localhost:6875;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-Proto $scheme;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    }
}

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

After enabling the site and obtaining certificates with Certbot, update the APP_URL in your docker-compose.yml to https://docs.yourdomain.com and restart the container.

Manual installation (Ubuntu 24.04 LTS) #

If you prefer bare-metal deployment:

# Install dependencies
sudo apt update
sudo apt install -y apache2 php8.3 php8.3-curl php8.3-mbstring php8.3-ldap \
    php8.3-xml php8.3-zip php8.3-gd php8.3-mysql mysql-server git composer

# Clone BookStack
cd /var/www
git clone https://github.com/BookStackApp/BookStack.git --branch v26.03.4 --depth 1
cd BookStack

# Install PHP dependencies
composer install --no-dev

# Copy and configure environment
cp .env.example .env
php artisan key:generate

# Edit .env with your database credentials
# DB_HOST=localhost, DB_DATABASE=bookstack, DB_USERNAME=bookstack, DB_PASSWORD=...

# Run migrations
php artisan migrate

# Set permissions
chown -R www-data:www-data /var/www/BookStack
chmod -R 755 /var/www/BookStack
chmod -R 775 /var/www/BookStack/storage /var/www/BookStack/bootstrap/cache

The manual route gives you more control but requires you to manage PHP, the web server, and MySQL separately. For production, Docker is the recommended path.

LDAP & SSO Integration #

BookStack supports multiple authentication backends. For enterprise deployments, LDAP or SAML integration is essential.

LDAP Authentication (Active Directory / OpenLDAP) #

# Add to your .env file
AUTH_METHOD=ldap
LDAP_SERVER=ldap.company.com
LDAP_BASE_DN="ou=users,dc=company,dc=com"
LDAP_DN="cn=bookstack,ou=service,dc=company,dc=com"
LDAP_PASS=service_account_password
LDAP_USER_FILTER="(&(uid=${user}))"
LDAP_VERSION=3
LDAP_TLS=true
LDAP_ID_ATTRIBUTE=uid
LDAP_DISPLAY_NAME_ATTRIBUTE=cn
LDAP_EMAIL_ATTRIBUTE=mail

After restarting the container, BookStack will authenticate users against your LDAP directory. Users are auto-provisioned on first login, so you do not need to manually create accounts.

SAML 2.0 (for Okta, Azure AD, OneLogin) #

# SAML configuration in .env
AUTH_METHOD=saml2
SAML2_NAME=SSO
SAML2_EMAIL_ATTRIBUTE=email
SAML2_EXTERNAL_ID_ATTRIBUTE=name_id
SAML2_DISPLAY_NAME_ATTRIBUTES=first_name|last_name
SAML2_IDP_ENTITYID=https://your-idp.example.com/metadata
SAML2_IDP_SSO=https://your-idp.example.com/sso
SAML2_IDP_x509="MIIDXTCCAkWgAwIBAgIJAJC1HiIA..."

Image Management & Content Editing #

BookStack ships with two editors. The WYSIWYG editor (TinyMCE-based) is the default — it handles images via drag-and-drop upload, supports tables, code blocks with syntax highlighting, and callout blocks for tips and warnings. The Markdown editor offers a split-screen experience with live preview, ideal for developers who prefer writing in Markdown.

Uploading images is straightforward:

# In Markdown mode - images are uploaded to BookStack's gallery
![Alt text](uploaded-image-name.png)

# Image gallery is accessible from the editor toolbar
# All uploaded images are stored in the bookstack_app_data volume

BookStack also supports embedded diagrams via Draw.io integration. When you insert a diagram, BookStack stores the Draw.io source XML alongside the rendered image, so you can re-edit diagrams later without losing the source.

Benchmarks & Real-World Performance #

I ran BookStack on a 2 vCPU / 4GB RAM VPS with 50 concurrent simulated users reading and editing pages. The results:

On a DigitalOcean $24/month Droplet, BookStack comfortably serves 50+ active users. The PHP-FPM process pool handles concurrency well, and MySQL FULLTEXT search performs adequately for knowledge bases under 5,000 pages. Beyond that, you may want to consider adding a dedicated search index.

For context: Confluence Cloud charges $6.05/user/month. At 50 users, that is $302.50/month. BookStack on a $24/month VPS saves $3,342 per year — and your data stays on infrastructure you control.

Integration with CI/CD and Developer Tools #

GitHub Actions: Automated Documentation Publishing #

# .github/workflows/publish-docs.yml
name: Publish API Docs to BookStack

on:
  push:
    branches: [main]
    paths: ['docs/**']

jobs:
  publish:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      
      - name: Upload to BookStack via API
        run: |
          curl -X PUT \
            -H "Authorization: Token ${{ secrets.BOOKSTACK_API_TOKEN }}" \
            -H "Content-Type: application/json" \
            -d '{"name": "API Documentation", "html": "'"$(cat docs/api.html | base64 -w 0)"'"}' \
            "https://docs.yourdomain.com/api/pages/42"

BookStack exposes a REST API for programmatic content management. Generate API tokens in Settings → API. The API supports CRUD operations on shelves, books, chapters, and pages, plus image upload and search.

Backup Automation #

#!/bin/bash
# /opt/scripts/backup-bookstack.sh

BACKUP_DIR="/backups/bookstack"
DATE=$(date +%Y%m%d_%H%M%S)

# Backup database
docker exec bookstack_db mysqldump -u bookstack -p'your_password' bookstackdb \
  | gzip > "$BACKUP_DIR/bookstack_db_$DATE.sql.gz"

# Backup application data (uploads, config)
tar czf "$BACKUP_DIR/bookstack_app_$DATE.tar.gz" -C /path/to ./bookstack_app_data

# Keep only last 14 days
find "$BACKUP_DIR" -name "*.gz" -mtime +14 -delete

Add this to cron for daily backups: 0 3 * * * /opt/scripts/backup-bookstack.sh

Monitoring with Prometheus #

# Add to docker-compose.yml for monitoring
  node-exporter:
    image: prom/node-exporter:v1.7.0
    volumes:
      - /proc:/host/proc:ro
      - /sys:/host/sys:ro
    command:
      - '--path.procfs=/host/proc'
      - '--path.sysfs=/host/sys'

Health check script #

#!/bin/bash
# /opt/scripts/health-check-bookstack.sh

# Check if BookStack is responding
HTTP_CODE=$(curl -s -o /dev/null -w "%{http_code}" http://localhost:6875/login)

if [ "$HTTP_CODE" != "200" ]; then
    echo "ERROR: BookStack returned HTTP $HTTP_CODE"
    docker restart bookstack
    echo "Container restarted at $(date)"
else
    echo "OK: BookStack is healthy"
fi

Add to cron for automated health checks: */5 * * * * /opt/scripts/health-check-bookstack.sh

Advanced Usage: Production Hardening #

Enable HTTPS-only cookies #

# In your .env file
SESSION_SECURE_COOKIE=true

This ensures session cookies are only transmitted over HTTPS connections. Critical if your BookStack instance is exposed to the internet.

Custom theme via the module system (v26.03+) #

# Create a custom module directory
mkdir -p /config/www/themes/my_theme/modules/welcome_module

# bookstack-module.json
{
    "name": "welcome_module",
    "version": "1.0.0",
    "description": "Adds a welcome banner to the header"
}

# functions.php
<?php
use BookStack\Facades\Theme;
use BookStack\Theming\ThemeEvents;
use BookStack\Theming\ThemeViews;

Theme::listen(ThemeEvents::THEME_REGISTER_VIEWS, function (ThemeViews $themeViews) {
    $themeViews->renderAfter('layouts.parts.header', 'welcome', 10);
});

# views/welcome.blade.php
<div class="welcome-banner">
    Welcome, {{ user()->name }}! Check out the onboarding docs.
</div>

Install the module with: php artisan bookstack:install-module /path/to/module.zip

Page content filtering control #

# In .env (new in v25.12.4+)
# Options: false, true, or a comma-separated list of filter names
APP_CONTENT_FILTERING=default

# Available filters: script, form, iframe, object, embed, style, css_expression
# To disable style filtering (useful if you need inline styles):
APP_CONTENT_FILTERING=script,form,iframe,object,embed,css_expression

Comparison: BookStack vs. Alternatives #

BookStack wins when: Your team values structured hierarchy, wants a dead-simple setup, needs WYSIWYG + Markdown dual editing, and prefers PHP ecosystem familiarity.

Wiki.js wins when: You need real-time collaboration, prefer Node.js stacks, want GraphQL API access, or need more flexible content architecture.

DokuWiki wins when: You want zero database setup — it runs entirely on flat files. Best for tiny deployments where simplicity trumps features.

MediaWiki wins when: You are building a public encyclopedia-scale wiki. Overkill for most internal documentation needs.

Outline wins when: Your team wants a Notion-like block editor experience with real-time collaboration, and you are okay with a more complex self-hosted setup or the hosted pricing.

Limitations: An Honest Assessment #

BookStack is not the right tool for every documentation use case. Here is what it does not do well:

No real-time collaboration. Two users editing the same page simultaneously will overwrite each other. BookStack warns about stale edits but does not offer Google Docs-style real-time collaboration. If your workflow depends on simultaneous editing, use Outline or Wiki.js instead.

Opinionated hierarchy can feel restrictive. The shelf/book/chapter/page model is great for structured documentation but awkward for fluid, constantly-restructured knowledge bases. If your docs are more like a living knowledge graph than a reference library, Notion or Obsidian may fit better.

Limited public-facing documentation features. BookStack supports public visibility for bookshelves, but it is not designed for branded customer-facing docs sites. There is no built-in custom domain + SSL workflow, no versioning for public docs, and theming options are limited compared to dedicated docs platforms like Docusaurus or GitBook.

No built-in diagram editing (drawn inline). While BookStack integrates with Draw.io for diagrams, you open the Draw.io editor in a modal. You cannot draw directly on the page like you can in Excalidraw within Outline.

PHP stack may feel dated. Teams running entirely on Node.js or Go infrastructure may prefer a tool in their existing stack. That said, PHP deployment is well-understood and battle-tested — there is value in boring technology.

Frequently Asked Questions #

Can I migrate from Confluence to BookStack? #

There is no official Confluence importer, but you can export Confluence pages as HTML or Markdown and use the BookStack REST API to bulk-create pages. Community scripts exist for this migration path. For large-scale migrations, expect to spend some time restructuring content to fit BookStack’s book/chapter/page model.

How do I update BookStack? #

With Docker, updating is a one-liner: change the image tag in docker-compose.yml and run docker compose up -d. With manual installation, pull the latest release, run git pull or download the new release archive, then run php artisan migrate and clear caches. Always back up your database before updating — BookStack releases security patches monthly.

Does BookStack support two-factor authentication? #

BookStack does not have built-in TOTP/SMS 2FA as of v26.03. You can achieve MFA by using SAML or OIDC authentication with an identity provider that enforces 2FA (like Azure AD or Okta). Native TOTP support has been discussed in the community but is not on the immediate roadmap.

Can I use PostgreSQL instead of MySQL? #

BookStack officially supports MySQL and MariaDB. PostgreSQL support has been discussed but is not officially supported. If you need PostgreSQL, Wiki.js or Outline are better fits. For BookStack, stick with MySQL 8.0+ or MariaDB 10.6+.

What is the difference between the LinuxServer.io image and the official image? #

The lscr.io/linuxserver/bookstack image is community-maintained and widely used. It abstracts away PHP-FPM and Nginx configuration, making it the easiest way to run BookStack in Docker. There is no official Docker image from the BookStack maintainers — the LinuxServer image is the de facto standard.

How do backups work? #

Back up two things: the MySQL/MariaDB database (for all content and metadata) and the /config/www/files directory (for uploaded images and attachments). With the Docker setup shown above, both are in named volumes. A simple mysqldump plus tar of the app data volume is sufficient. Test your restore procedure quarterly.

Conclusion: Should You Run BookStack in 2026? #

If your team is tired of paying per-seat pricing for documentation tools, and you want a structured, opinionated wiki that forces good organization habits, BookStack is one of the best open-source options available in 2026. The PHP/Laravel stack is boring in the best way — predictable, well-documented, and easy to debug when things go wrong. The monthly security releases show active maintenance, and the v26.03 theme module system opens new customization possibilities.

For teams of 5 to 50 people who want internal documentation without vendor lock-in, BookStack pays for itself immediately. Self-host on a DigitalOcean Droplet, back up daily, and you have a documentation system that will outlast whatever SaaS tool is trending this quarter.

Join the dibi8.com community: Telegram group for daily open-source tool discussions, deployment tips, and troubleshooting help from 5,000+ developers.

Sources & Further Reading #

• BookStack Official Documentation
• BookStack GitHub Mirror
• BookStack Codeberg Repository
• BookStack v26.03 Release Notes
• LinuxServer.io BookStack Docker Image
• BookStack vs Wiki.js Comparison

Recommended Hosting & Infrastructure #

Before you deploy any of the tools above into production, you’ll need solid infrastructure. Two options dibi8 actually uses and recommends:

• DigitalOcean — $200 free credit for 60 days across 14+ global regions. The default option for indie devs running open-source AI tools.
• HTStack — Hong Kong VPS with low-latency access from mainland China. This is the same IDC that hosts dibi8.com — battle-tested in production.

Affiliate links — they don’t cost you extra and they help keep dibi8.com running.

Affiliate Disclosure #

This article contains affiliate links to DigitalOcean. If you sign up through our link, we receive a referral credit at no additional cost to you. We only recommend infrastructure we use ourselves. The BookStack project is free and open-source — no affiliate relationship exists with the BookStack maintainers.