Self-Hosting BookStack: A Wiki That Actually Gets Used

Every team starts with good intentions about documentation. Then the wiki becomes a graveyard of half-finished pages, outdated procedures, and documents that nobody can find because the folder structure makes sense only to the person who created it three years ago.

BookStack is a self-hosted wiki that tackles this with an opinionated organizational structure: Shelves contain Books, Books contain Chapters, and Chapters contain Pages. This hierarchy is rigid on purpose — it forces your documentation into a navigable structure instead of a flat pile of pages.

Why BookStack?

• Intuitive structure — Shelves > Books > Chapters > Pages. Everyone understands it.
• WYSIWYG and Markdown — Both editors available, switch per-page
• Full-text search — Searches across all content including attachments
• Granular permissions — Control access per shelf, book, or page
• Drawing and diagrams — Built-in drawing tool for diagrams
• API — Full REST API for automation and integration
• Authentication — LDAP, SAML2, OIDC, and social login support

The trade-off compared to wikis like Wiki.js or Outline: BookStack's organizational structure is more rigid. You can't create free-floating pages or build arbitrary hierarchies. For most teams, this constraint produces better documentation.

Docker Deployment

# docker-compose.yml
services:
  bookstack:
    image: lscr.io/linuxserver/bookstack:latest
    ports:
      - "6875:80"
    volumes:
      - bookstack_config:/config
    environment:
      - PUID=1000
      - PGID=1000
      - TZ=America/Los_Angeles
      - APP_URL=https://wiki.yourdomain.com
      - DB_HOST=db
      - DB_PORT=3306
      - DB_USER=bookstack
      - DB_PASS=bookstackpass
      - DB_DATABASE=bookstack
    depends_on:
      - db
    restart: unless-stopped

  db:
    image: mariadb:11
    volumes:
      - bookstack_db:/var/lib/mysql
    environment:
      - MYSQL_ROOT_PASSWORD=rootpassword
      - MYSQL_DATABASE=bookstack
      - MYSQL_USER=bookstack
      - MYSQL_PASSWORD=bookstackpass
    restart: unless-stopped

volumes:
  bookstack_config:
  bookstack_db:

docker compose up -d

BookStack is available at http://your-server:6875. Default login: [email protected] / password. Change this immediately.

Important: Set APP_URL to your actual public URL. BookStack uses this for generating links, redirects, and email content. Getting this wrong breaks navigation.

Organizing Your Documentation

BookStack's hierarchy maps well to how most teams think about documentation:

Shelves = Departments or top-level categories

• "Engineering"
• "Operations"
• "Onboarding"
• "Product"

Books = Major topics within a shelf

• Engineering > "Deployment Procedures"
• Engineering > "Architecture Decisions"
• Operations > "Runbooks"

Chapters = Sections within a book

• Deployment Procedures > "Production Deploys"
• Deployment Procedures > "Staging Environment"
• Deployment Procedures > "Rollback Procedures"

Pages = Individual documents

• Production Deploys > "How to deploy the API"
• Production Deploys > "Database migration checklist"

This structure means every page has a clear location. When someone asks "where's the deploy documentation?", the answer is obvious.

Editor Features

BookStack offers two editors:

WYSIWYG editor (default)

The rich text editor supports:

• Formatted text, headings, lists, tables
• Image uploads (drag and drop)
• Code blocks with syntax highlighting
• Callout boxes (info, warning, danger)
• Embedded drawings (built-in diagram tool)
• File attachments
• Page includes (embed content from other pages)

Markdown editor

Switch to Markdown in your user profile settings. The Markdown editor provides:

• Live preview
• Standard Markdown syntax
• All the same attachment and embed features

Permissions and Access Control

BookStack has a granular permission system:

Roles

Create roles with specific capabilities:

• Admin — Full access to everything
• Editor — Can create and edit content in assigned areas
• Viewer — Read-only access

Per-item permissions

Override default permissions at any level:

1. Navigate to the shelf, book, chapter, or page
2. Click Permissions
3. Enable Custom Permissions
4. Set per-role access (View, Create, Update, Delete)

This lets you have public documentation (visible to all staff) alongside restricted areas (HR policies visible only to managers, for example).

SSO Authentication

OIDC (works with Keycloak, Authelia, Authentik)

In BookStack's .env or environment variables:

AUTH_METHOD=oidc
OIDC_NAME="SSO Login"
OIDC_DISPLAY_NAME_CLAIMS=name
OIDC_CLIENT_ID=bookstack
OIDC_CLIENT_SECRET=your-client-secret
OIDC_ISSUER=https://auth.yourdomain.com/realms/yourrealm
OIDC_ISSUER_DISCOVER=true

LDAP

AUTH_METHOD=ldap
LDAP_SERVER=ldap://ldap.yourdomain.com:389
LDAP_BASE_DN="dc=yourdomain,dc=com"
LDAP_DN="cn=admin,dc=yourdomain,dc=com"
LDAP_PASS=ldappassword
LDAP_USER_FILTER="(&(uid=${user}))"
LDAP_VERSION=3

API Usage

BookStack has a full REST API for automation. Generate an API token in your user profile.

# List all books
curl 'https://wiki.yourdomain.com/api/books' \
  -H 'Authorization: Token your-token-id:your-token-secret'

# Create a new page
curl 'https://wiki.yourdomain.com/api/pages' \
  -X POST \
  -H 'Authorization: Token your-token-id:your-token-secret' \
  -H 'Content-Type: application/json' \
  -d '{
    "book_id": 1,
    "name": "Automated Report",
    "markdown": "## Weekly Metrics\n\nGenerated automatically."
  }'

# Search content
curl 'https://wiki.yourdomain.com/api/search?query=deployment' \
  -H 'Authorization: Token your-token-id:your-token-secret'

The API is useful for:

• Automatically generating documentation pages from scripts
• Importing content from other systems
• Building integrations with CI/CD pipelines (post deploy notes automatically)
• Syncing documentation with other tools

BookStack vs Other Wiki Platforms

When to choose BookStack

• You want enforced organizational structure that prevents wiki chaos
• You need a WYSIWYG editor that non-technical team members can use
• You want minimal resource usage
• You need granular per-item permissions

When to choose alternatives

• Wiki.js if you want more editor options and a modern UI
• Outline if your team prefers a Notion-like block editor
• Confluence if you're deep in the Atlassian ecosystem (Jira integration)

Backup Strategy

BookStack stores data in two places:

# Database backup
docker exec bookstack-db-1 mariadb-dump -u bookstack -pbookstackpass bookstack > bookstack-backup.sql

# File backup (uploads, images, config)
docker cp bookstack-bookstack-1:/config ./bookstack-config-backup

The Bottom Line

BookStack works because it's opinionated about the one thing most wikis get wrong: organization. The Shelves > Books > Chapters > Pages hierarchy isn't flexible by design. It forces documentation into a structure that other people can navigate without a map. If your team's documentation has devolved into a flat list of pages that nobody can find anything in, BookStack's rigid structure is exactly the constraint you need.