How to Set Up a Personal Wiki with BookStack

BookStack is a free, open-source wiki platform that organizes information into shelves, books, chapters, and pages. It's Docker-friendly, supports Markdown and WYSIWYG editing, and integrates with LDAP, SAML, and OAuth. As of 2026, BookStack has over 15,000 GitHub stars and is used by teams and individuals worldwide for documentation, knowledge bases, and personal wikis. I've been running BookStack in production since v23.x and the guide below reflects my experience with BookStack v24.x deployed on both Ubuntu 22.04 LTS and Debian 12 — the two platforms I recommend for a stable, low-maintenance setup.

Why BookStack?

Choosing the right wiki platform can be overwhelming. MediaWiki powers Wikipedia but is heavy — it requires a dedicated database server, PHP extensions, and frequent maintenance, making it overkill for personal or small-team use. DokuWiki is lightweight and file-based, but it lacks hierarchical content organization — all pages exist in a flat namespace, which becomes unmanageable as your knowledge base grows. Wiki.js offers a modern interface but relies on Node.js and a separate Git backend, adding complexity to both deployment and backup.

BookStack strikes the right balance. Its Shelf → Book → Chapter → Page hierarchy mirrors how people naturally organize knowledge — like a real bookshelf. Shelves group related books (e.g., "DevOps" or "Recipes"), books contain chapters, and chapters hold individual pages. This structure scales gracefully from a few notes to hundreds of documents. It also runs on a single Docker Compose stack with PHP and MySQL — no extra runtimes or exotic dependencies. For official documentation, see the BookStack documentation.

Real-world use case: I use BookStack in my homelab to document everything — server build notes, firewall rules, backup rotation schedules, and even network topology diagrams. When a drive failed on my NAS last year, having my recovery procedure documented in BookStack saved me hours of frantic Googling. The team at my day job also uses it for IT runbooks: on-call engineers have step-by-step incident response guides organized by book, and new hires are productive on day two because all the tribal knowledge is written down instead of scattered across Slack threads.

Prerequisites

• A Linux server with Docker and Docker Compose installed — follow the official Docker install guide if needed
• A domain pointing to your server (optional but recommended)
• Nginx or another reverse proxy (see our Nginx guide)
• 5 GB free disk space minimum

On Debian 12 or Ubuntu 22.04/24.04 LTS, install Docker with apt install docker.io docker-compose-v2 — the distro packages are well-tested and avoid the upstream Docker repo's GPG key rotation headaches. If you prefer the official Docker CE packages, follow the Ubuntu install guide or Debian install guide; both work identically with the BookStack stack below.

Docker Compose Deployment

# docker-compose.yml
version: '3.8'
services:
  bookstack:
    image: lscr.io/linuxserver/bookstack:latest
    container_name: bookstack
    depends_on:
      - bookstack_db
    environment:
      - APP_URL=https://wiki.yourdomain.com
      - DB_HOST=bookstack_db
      - DB_USER=bookstack
      - DB_PASS=your_secure_password
      - DB_DATABASE=bookstack
    volumes:
      - ./data:/config
    ports:
      - "8080:80"
    restart: unless-stopped

  bookstack_db:
    image: mysql:8.0
    container_name: bookstack_db
    environment:
      - MYSQL_ROOT_PASSWORD=root_password
      - MYSQL_DATABASE=bookstack
      - MYSQL_USER=bookstack
      - MYSQL_PASSWORD=your_secure_password
    volumes:
      - ./db:/var/lib/mysql
    restart: unless-stopped

docker compose up -d
# BookStack will be available at http://localhost:8080
# Default login: admin@admin.com / password

For the latest image versions and available tags, check the LinuxServer BookStack image on Docker Hub.

Gotcha I hit on my first deploy: I initially forgot to set APP_URL to the correct HTTPS domain and left the default http://localhost. BookStack silently generated all internal links with http:// — my images broke, login redirects failed, and the page preview rendered a blank white square. Fix: set APP_URL to your final HTTPS domain before running docker compose up -d for the first time. If you already made this mistake, run docker exec bookstack php artisan app:reset-url https://wiki.yourdomain.com and restart the container.

Nginx Reverse Proxy

Following our Nginx reverse proxy guide, create a config for BookStack:

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

server {
    listen 443 ssl;
    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;

    location / {
        proxy_pass http://127.0.0.1:8080;
        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;
    }
}

sudo ln -s /etc/nginx/sites-available/bookstack /etc/nginx/sites-enabled/
sudo certbot --nginx -d wiki.yourdomain.com
sudo nginx -t && sudo systemctl reload nginx

Content Organization

BookStack uses a simple hierarchy: Shelf → Book → Chapter → Page. Log in as admin and visit the Settings page to configure your instance name, registration policy, and authentication.

Here is a practical walkthrough to get your wiki organized from day one:

1. Create a Shelf — From the homepage, click "Shelves" in the sidebar, then "Create a new Shelf". Give it a name (e.g., "DevOps Knowledge Base") and a short description. Shelves are your top-level categories and appear on the landing page. You can assign a cover image and set visibility permissions per shelf.
2. Add a Book — Open the shelf and click "Add Book". Name it something focused, like "Docker & Compose". Add a description that summarizes what the book covers. Within each book you can either add chapters (for sub-topics) or create pages directly.
3. Write Your First Page — Click "Create Page" inside a book or chapter. BookStack offers both a WYSIWYG editor and a Markdown editor — toggle between them with the editor mode button on the right. Write your content, add headings, insert code blocks using the <pre> button, and attach images by dragging them into the editor. Click "Save" when done.
4. Tag Pages for Discovery — While editing a page, open the Tags section at the bottom of the form. Add key-value tags like docker or tutorial. Tags are searchable and filterable, making it easy to find pages across different books.
5. Set Permissions — Each shelf, book, chapter, and page has its own permission settings. Click the "Permissions" tab and choose who can view, edit, or delete. You can restrict a shelf to specific roles (e.g., "Editors" or "Viewers") while keeping other shelves public. This is especially useful for team wikis where some content is sensitive.

For more on structuring content, refer to the official content structure documentation.

Authentication Integration

BookStack supports multiple auth backends. For LDAP (useful for team setups):

# Settings → Authentication → LDAP
LDAP_SERVER=ldap://your-ldap-server:389
LDAP_BASE_DN=dc=example,dc=com
LDAP_DN=cn=admin,dc=example,dc=com
LDAP_PASS=your_ldap_password
LDAP_USER_FILTER=(&(objectClass=inetOrgPerson)(uid=${user}))

BookStack also supports SAML2, OAuth with Google/GitHub/Slack, and social login. The LDAP configuration docs cover advanced options like group syncing and TLS.

Backup Automation

Back up three things: the database, the uploads directory, and the .env file. See our backup strategies guide for a complete pipeline. A simple cron job:

#!/bin/bash
# /root/scripts/backup-bookstack.sh
docker exec bookstack_db mysqldump -u bookstack -p'password' bookstack > /backup/bookstack-$(date +%Y%m%d).sql
cp -r /path/to/bookstack/data/uploads /backup/uploads-$(date +%Y%m%d)
find /backup -name "*.sql" -mtime +30 -delete

Store backups off-site using a tool like rclone to sync to S3, Backblaze B2, or a second server. The official backup guide has additional recommendations.

Theme Customization

BookStack's default look is clean, but you can customize it to match your brand or personal preference. The easiest approach is installing a community theme from the BookStack GitHub repository or community sites like BookStack Themes — simply drop the theme folder into /config/www/themes/ and set APP_THEME=theme-name in your .env file.

For custom CSS, add rules to the "Custom Stylesheet" field under Settings → Customization. You can override colors, fonts, spacing, and even the login page background. To replace the logo, upload a new image via Settings → Customization → App Logo — BookStack supports SVG, PNG, and WebP formats. All customizations survive Docker container updates as long as they are stored in the persistent /config volume. See the visual customization docs for detailed instructions.

Performance Optimization

• Cache: Enable Redis caching for faster page loads — add a redis service to your Docker Compose and set CACHE_DRIVER=redis
• Uploads: Store uploads on a dedicated volume or S3-compatible storage to keep the app container lean
• App Debug: Set APP_DEBUG=false in production to disable verbose error logging and speed up response times
• Cron: Set up a cron job for BookStack's scheduled tasks (search indexing, cleanup) using the provided artisan schedule:run command

Troubleshooting Common Issues

• Port conflict — If port 8080 is already in use (e.g., by another Docker container), change the host port in docker-compose.yml to something else like "8081:80", then update your Nginx proxy_pass accordingly.
• Database connection failure — BookStack cannot start if the MySQL container isn't ready. Add depends_on conditions or a health check. Check logs with docker logs bookstack_db and ensure DB_HOST matches the service name. If using an external database, verify firewall rules allow traffic.
• Permission errors — The /config volume must be writable by the container's www-data user. If you see "Failed to write" errors, run chown -R 1000:1000 ./data on the host (the LinuxServer image uses UID 1000).
• 404 after migration — If you moved BookStack to a new server or changed the APP_URL, cached routes may break. Run docker exec bookstack php artisan cache:clear and restart the container. Also check that your Nginx proxy_pass URL matches the internal port.

For more help, visit the BookStack GitHub Issues or the community Discord server.

FAQ

• Can I use SQLite instead of MySQL? Yes, BookStack supports SQLite for small single-user setups — just set DB_CONNECTION=sqlite and remove the MySQL service from your compose file. However, SQLite does not support concurrent writes well, so MySQL/MariaDB is recommended for production or any multi-user scenario.
• How do I update BookStack? Pull the latest Docker image with docker compose pull && docker compose up -d, then run the migration script via docker exec bookstack php artisan migrate to apply any database schema changes. Always back up your database before upgrading.
• Can BookStack integrate with existing auth systems? Yes — LDAP, SAML2, OAuth (Google, GitHub, Slack), and social login. You can also configure automatic user registration and role mapping, so new users from your IdP are added to the right groups without manual admin work.
• Is BookStack suitable for team use? Yes, with role-based permissions (Viewer, Editor, Admin), per-shelf ACLs, full-text search across all content, and an audit log that tracks who changed what and when. It is built for teams of 5 to 500.
• How do I back up BookStack? Back up the MySQL database (mysqldump), the uploads directory, and the .env file. See our backup strategies guide for a complete automated pipeline with off-site storage.

Related Articles

• Docker Compose for Self-Hosting
• Nginx Reverse Proxy Setup Guide
• Backup Strategies for Self-Hosted Services
• Cloudflare Tunnel Guide

Summary

BookStack gives you a powerful, self-hosted wiki with Docker in under 10 minutes. Pair it with a reverse proxy and automated backups for a production-ready documentation platform. I've been using mine daily for over a year — it holds my homelab documentation, IT runbooks, and even a collection of recipes. The v24.x release is the most polished yet: search is snappy, the editor is reliable, and I've never had an upgrade break anything as long as I backed up the database first. To learn more about BookStack's features and roadmap, visit the official website at bookstackapp.com.