# BookStack Documentation

> Simple, self-hosted wiki platform for organizing and storing information.

- Category: Productivity & Collaboration
- Difficulty: beginner
- Components: bookstack, mariadb
- Tags: wiki, documentation, bookstack, knowledge-base
- Source: https://docker.recipes/productivity/bookstack-wiki

## Overview

BookStack is a modern, self-hosted wiki platform designed to organize and store information in a structured, searchable format. Developed in PHP and built with simplicity in mind, BookStack offers an intuitive hierarchical structure using Shelves, Books, Chapters, and Pages to organize documentation, knowledge bases, and collaborative content. The platform emphasizes ease of use while providing powerful features like real-time collaborative editing, comprehensive search capabilities, and flexible user permission systems.

This deployment combines BookStack with MariaDB to create a robust documentation platform where MariaDB's enhanced MySQL compatibility and performance optimizations provide reliable data storage for wiki content, user accounts, and revision histories. MariaDB's Aria storage engine offers improved crash recovery for BookStack's frequent content updates, while its enhanced JSON functions support BookStack's metadata and configuration storage requirements.

This stack is ideal for teams, organizations, and individuals who need a professional wiki solution without the complexity of enterprise platforms like Confluence. Small to medium businesses can deploy this for internal documentation, software development teams can maintain technical wikis, and educational institutions can create collaborative knowledge repositories with full control over their data and customization options.

## Features

- WYSIWYG and markdown editor with real-time collaborative editing and revision tracking
- Hierarchical content organization with Shelves containing Books, Chapters, and Pages structure
- Advanced search functionality with full-text search across all content and attachments
- Flexible role-based permissions with granular control down to individual pages and books
- Multiple authentication methods including LDAP, SAML, and OpenID Connect integration
- File attachment system with image galleries and drawing tools for diagrams
- MariaDB's Aria storage engine providing enhanced crash recovery for wiki content
- BookStack's API integration with MariaDB's JSON functions for metadata management

## Use cases

- Internal company wikis and knowledge bases for employee onboarding and procedures
- Software development teams maintaining technical documentation and API references
- Educational institutions creating collaborative learning resources and course materials
- IT departments documenting infrastructure, troubleshooting guides, and system procedures
- Project management teams organizing project documentation and meeting notes
- Personal knowledge management for researchers and content creators
- Community organizations maintaining member resources and organizational information

## Prerequisites

- Minimum 1GB RAM for MariaDB optimal performance with BookStack's content storage
- Available port 6875 for BookStack web interface access
- Docker and Docker Compose installed with support for bridge networks
- Environment variables configured for TZ, APP_URL, DB_PASSWORD, and DB_ROOT_PASSWORD
- Basic understanding of wiki concepts and content organization hierarchy
- SSL certificate and reverse proxy knowledge for production HTTPS deployment

## docker-compose.yml

```yaml
services:
  bookstack:
    image: lscr.io/linuxserver/bookstack:latest
    container_name: bookstack
    environment:
      - PUID=1000
      - PGID=1000
      - TZ=${TZ}
      - APP_URL=${APP_URL}
      - DB_HOST=db
      - DB_PORT=3306
      - DB_USER=bookstack
      - DB_PASS=${DB_PASSWORD}
      - DB_DATABASE=bookstack
    volumes:
      - bookstack-data:/config
    ports:
      - "6875:80"
    depends_on:
      - db
    networks:
      - bookstack-network
    restart: unless-stopped

  db:
    image: mariadb:10.11
    container_name: bookstack-db
    environment:
      - MYSQL_ROOT_PASSWORD=${DB_ROOT_PASSWORD}
      - MYSQL_DATABASE=bookstack
      - MYSQL_USER=bookstack
      - MYSQL_PASSWORD=${DB_PASSWORD}
    volumes:
      - mariadb-data:/var/lib/mysql
    networks:
      - bookstack-network
    restart: unless-stopped

volumes:
  bookstack-data:
  mariadb-data:

networks:
  bookstack-network:
    driver: bridge
```

## .env

```bash
# BookStack
TZ=UTC
APP_URL=http://localhost:6875
DB_PASSWORD=secure_bookstack_password
DB_ROOT_PASSWORD=secure_root_password
```

## Usage notes

- Web UI at http://localhost:6875
- Default login: admin@admin.com / password
- Change default password immediately
- Organize with Shelves > Books > Chapters > Pages
- Supports LDAP, SAML, OIDC auth

## Troubleshooting

- BookStack shows database connection error: Verify DB_PASSWORD matches MYSQL_PASSWORD and ensure MariaDB container is running
- Login page shows 'Application key not set': Check APP_URL environment variable matches your actual domain and restart BookStack container
- File uploads failing with permission errors: Ensure PUID and PGID match your host user permissions for bookstack-data volume
- MariaDB container exits with 'Can't connect to server': Check mariadb-data volume permissions and verify MYSQL_ROOT_PASSWORD is set
- BookStack performance slow with large wikis: Increase MariaDB memory allocation and enable query cache in MariaDB configuration
- Authentication integration failing: Verify APP_URL uses HTTPS for SAML/OIDC and check BookStack logs for certificate validation errors

