# BookStack

> Simple wiki and documentation platform.

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

## Overview

BookStack is a self-hosted documentation and wiki platform built with PHP and Laravel, designed to organize information in an intuitive hierarchical structure. Created by Dan Brown in 2016, BookStack emphasizes simplicity and user-friendliness while providing powerful documentation features like WYSIWYG editing, page templates, and comprehensive search functionality. The platform uses a logical organizational system of Shelves containing Books, which contain Chapters and Pages, making it easy for teams to structure their knowledge base naturally. This deployment pairs BookStack with MariaDB 11, which serves as the primary database backend for storing all documentation content, user accounts, and application metadata. MariaDB's enhanced MySQL compatibility ensures optimal performance for BookStack's Laravel framework while providing additional features like improved connection handling through thread pooling and better storage engine options. The combination delivers a robust documentation solution that can handle everything from personal note-taking to enterprise-wide knowledge management, with MariaDB's reliability ensuring your documentation remains highly available and performant even under heavy usage.

## Features

- Hierarchical content organization with Shelves, Books, Chapters, and Pages structure for logical documentation flow
- Dual editing modes supporting both WYSIWYG visual editor and Markdown syntax for different user preferences
- Multi-format export capabilities including PDF generation, HTML export, and Markdown conversion for content portability
- Advanced search functionality with full-text indexing powered by MariaDB's enhanced search capabilities
- Role-based permission system with granular access controls at shelf, book, chapter, and page levels
- Drawing and diagramming tools with built-in image annotation and markup features
- Page templates and custom HTML support for standardized documentation formats
- MariaDB's Aria storage engine providing crash-safe operations and improved performance for BookStack's data

## Use cases

- Technical documentation hubs for software development teams managing API docs, deployment guides, and coding standards
- IT knowledge bases storing troubleshooting procedures, network diagrams, and infrastructure documentation
- Project wikis for tracking requirements, specifications, and collaborative planning documents
- Educational institutions creating course materials, student handbooks, and research documentation
- Small business operations manuals documenting processes, procedures, and training materials
- Personal knowledge management systems for researchers and professionals organizing notes and references
- Client documentation portals for agencies and consultants sharing guides and project information

## Prerequisites

- Minimum 1GB RAM for optimal MariaDB performance with BookStack's database operations
- Docker and Docker Compose installed with support for environment variable substitution
- Port 6875 available for BookStack web interface access
- Environment variables configured for DB_USER, DB_PASSWORD, DB_NAME, and DB_ROOT_PASSWORD
- Basic understanding of user permission systems for configuring BookStack access controls
- Storage space planning for document uploads, images, and database growth over time

## docker-compose.yml

```yaml
services:
  bookstack:
    image: linuxserver/bookstack:latest
    container_name: bookstack
    restart: unless-stopped
    environment:
      PUID: 1000
      PGID: 1000
      APP_URL: http://localhost:6875
      DB_HOST: mariadb
      DB_USER: ${DB_USER}
      DB_PASS: ${DB_PASSWORD}
      DB_DATABASE: ${DB_NAME}
    volumes:
      - bookstack_config:/config
    ports:
      - "6875:80"
    depends_on:
      - mariadb
    networks:
      - bookstack

  mariadb:
    image: mariadb:11
    container_name: bookstack-mariadb
    environment:
      MARIADB_ROOT_PASSWORD: ${DB_ROOT_PASSWORD}
      MARIADB_DATABASE: ${DB_NAME}
      MARIADB_USER: ${DB_USER}
      MARIADB_PASSWORD: ${DB_PASSWORD}
    volumes:
      - mariadb_data:/var/lib/mysql
    networks:
      - bookstack

volumes:
  bookstack_config:
  mariadb_data:

networks:
  bookstack:
    driver: bridge
```

## .env

```bash
DB_ROOT_PASSWORD=rootpassword
DB_NAME=bookstack
DB_USER=bookstack
DB_PASSWORD=changeme
```

## Usage notes

- Docs: https://www.bookstackapp.com/docs/
- Access at http://localhost:6875 - default: admin@admin.com / password
- Hierarchy: Shelves > Books > Chapters > Pages
- WYSIWYG and Markdown editors available
- Export to PDF, HTML, plaintext, or Markdown
- LDAP/SAML/OAuth authentication supported for enterprise

## Troubleshooting

- BookStack shows database connection error: Verify MariaDB container is running and DB_HOST matches the MariaDB service name
- Login fails with default credentials: Check if BookStack has fully initialized by viewing logs with docker logs bookstack
- File uploads not working: Ensure bookstack_config volume has proper write permissions for PUID/PGID 1000
- MariaDB container exits with code 1: Check that all required environment variables (MARIADB_ROOT_PASSWORD, MARIADB_DATABASE) are properly set
- BookStack interface loads but images/assets missing: Verify APP_URL environment variable matches your actual access URL
- Performance issues with large wikis: Increase MariaDB memory allocation using innodb_buffer_pool_size configuration

