Setting Up BookStack for Documentation Management

Good documentation is the backbone of any project, whether it’s a home lab setup, a small business wiki, or technical notes for your team. But where do you store it? Google Docs lacks structure, Notion locks you into their platform, and Confluence is overkill (and expensive) for most self-hosters.

Enter BookStack—a free, open-source, self-hosted documentation platform that strikes the perfect balance between simplicity and power. Built with PHP and MySQL, BookStack organizes content into Books, Chapters, and Pages, making it intuitive for both writers and readers.

What is BookStack?

BookStack is a documentation and wiki platform designed for creating and organizing knowledge bases. Think of it as a digital library where each “Book” contains “Chapters” with individual “Pages” of content.

Why Choose BookStack?

Intuitive Structure
The Book → Chapter → Page hierarchy makes sense immediately. No complex wikis or confusing folder structures.

WYSIWYG Editor
Write documentation using a visual editor (like Word) or switch to Markdown. No learning curve required.

Beautiful Interface
Clean, modern design that looks professional without customization. Dark mode included.

Powerful Search
Full-text search across all content with instant results. Tag pages for better discoverability.

Collaboration Features
Multiple users, role-based permissions, comments, page history, and activity tracking.

Self-Hosted & Open Source
Your data stays on your server. MIT licensed, active development, no vendor lock-in.

Use Cases for BookStack

Personal Knowledge Base

• Home lab documentation
• Technical notes and tutorials
• Project ideas and planning
• Book notes and research

Team Documentation

• Company wikis
• Onboarding guides
• Process documentation
• Meeting notes

Technical Documentation

• API documentation
• Software architecture
• Deployment procedures
• Troubleshooting guides

Education

• Course materials
• Student guides
• Research notes
• Collaborative projects

Requirements

Before you begin:

• A server running Docker and Docker Compose
• At least 1GB RAM (2GB recommended)
• 5-10GB disk space (grows with content)
• Port 8080 available (customizable)
• Basic command line knowledge

Installing BookStack with Docker

Step 1: Create Docker Compose File

Create a directory for BookStack:

mkdir -p ~/bookstack
cd ~/bookstack

Create docker-compose.yml:

version: '3.8'

services:
  bookstack:
    image: lscr.io/linuxserver/bookstack:latest
    container_name: bookstack
    environment:
      - PUID=1000
      - PGID=1000
      - TZ=America/New_York
      - APP_URL=http://YOUR_SERVER_IP:8080
      - DB_HOST=bookstack_db
      - DB_PORT=3306
      - DB_DATABASE=bookstackapp
      - DB_USERNAME=bookstack
      - DB_PASSWORD=changeme_secure_password
    volumes:
      - ./config:/config
    ports:
      - 8080:80
    restart: unless-stopped
    depends_on:
      - bookstack_db

  bookstack_db:
    image: lscr.io/linuxserver/mariadb:latest
    container_name: bookstack_db
    environment:
      - PUID=1000
      - PGID=1000
      - TZ=America/New_York
      - MYSQL_ROOT_PASSWORD=changeme_root_password
      - MYSQL_DATABASE=bookstackapp
      - MYSQL_USER=bookstack
      - MYSQL_PASSWORD=changeme_secure_password
    volumes:
      - ./database:/config
    restart: unless-stopped

volumes:
  bookstack-data:
  bookstack-db:

Important: Change these values:

• TZ: Your timezone
• APP_URL: Your server IP or domain
• DB_PASSWORD: Strong database password
• MYSQL_ROOT_PASSWORD: Strong root password
• PUID/PGID: Your user ID (run id command)

Step 2: Start BookStack

Launch the containers:

docker-compose up -d

Wait about 30 seconds for initialization, then verify:

docker ps

You should see two containers running: bookstack and bookstack_db.

Step 3: Initial Access

Open your browser and navigate to:

Default credentials:

• Email: [email protected]
• Password: password

⚠️ Change these immediately after logging in!

Initial Configuration

Change Admin Password

1. Click your profile icon (top-right)
2. Go to My Account
3. Click Change Password
4. Enter new secure password
5. Save changes

Update Admin Email

1. My Account → Edit Profile
2. Change email from [email protected] to your real email
3. Save

Configure Application Settings

Go to Settings (gear icon in top-right):

General Settings

• Application Name: Change from “BookStack” to your wiki name
• Application Logo: Upload a custom logo (optional)
• Application Icon: Upload a favicon (optional)

Registration Settings

• Allow Public Registration: Disable unless you want open signups
• Email Confirmation: Enable if allowing registrations
• Restrict Registration: Set to specific domains if needed

Maintenance

• Maintenance Mode: Keep off (use when performing updates)

Create Your First Book

1. Click + Create New → Book
2. Enter a title: “Home Lab Documentation”
3. Add a description (optional)
4. Click Create Book

Create a Chapter

1. Inside your book, click + New Chapter
2. Title: “Server Setup”
3. Description (optional)
4. Create Chapter

Create a Page

1. Inside your chapter, click + New Page
2. Title: “Ubuntu Server Installation”
3. Write content using the editor
4. Click Save (top-right)

Using the Editor

BookStack offers two editing modes:

WYSIWYG Editor (Default)

Visual editor similar to Microsoft Word:

• Bold, italic, headings
• Bullet lists, numbered lists
• Insert images, links, tables
• Code blocks, callouts
• Drawing tools

Toolbar options:

• Paragraph styles (H1-H6)
• Text formatting
• Lists and indentation
• Insert media
• Insert table
• Insert code block
• Insert drawing
• Full-screen mode

Markdown Editor

Switch to Markdown for faster writing:

1. Edit a page
2. Click the three dots (…) → Switch to Markdown Editor
3. Write in Markdown syntax

Common Markdown:

# Heading 1
## Heading 2
**Bold** and *italic*

- Bullet point
- Another point

1. Numbered list
2. Second item

[Link text](https://example.com)

![Image](image-url.jpg)

`inline code`

​```bash
# Code block
docker ps
​```

Toggle back to WYSIWYG anytime.

Advanced Features

Images and Attachments

Upload images:

1. Edit page → Insert → Image
2. Drag & drop or click to upload
3. Images stored in BookStack

Upload attachments:

1. Page view → Attachments tab
2. Click + Attach File
3. Upload PDFs, ZIPs, docs, etc.
4. Attachments appear at bottom of page

Embed drawings:

1. Edit page → Insert → Drawing
2. Use built-in drawing tool
3. Save and insert

Page Templates

Create templates for consistent formatting:

1. Create a page with your desired structure
2. Edit page → three dots (…) → New Template from Page
3. Name your template
4. When creating new pages, select template from dropdown

Example templates:

• Meeting notes (date, attendees, agenda, notes, action items)
• Server documentation (specs, OS, services, ports, backups)
• Troubleshooting guide (problem, symptoms, solution, prevention)

Tags and Search

Add tags to pages:

1. Edit page → scroll to bottom
2. Click + Add Tag
3. Enter tag name (e.g., “docker”, “security”, “tutorial”)
4. Save page

Search content:

• Use search bar at top
• Filter by tags, books, chapters
• Advanced search: tag:docker "nginx"

Permissions and Roles

Control who can view and edit content.

Default Roles

• Admin: Full access, manage settings
• Editor: Create/edit all content
• Viewer: Read-only access

Create Custom Roles

1. Settings → Roles
2. + Create New Role
3. Name: “Developer”
4. Permissions: Check boxes for allowed actions
   • View any content
   • Create pages/chapters
   • Edit own content
   • No delete permissions
5. Save role

Assign Users to Roles

1. Settings → Users
2. Click user → Edit
3. Select role
4. Save

Book-Level Permissions

1. View a book → three dots (…) → Permissions
2. Enable Custom Permissions
3. Set roles: Public/Logged In/Roles
4. Choose: View, Create, Update, Delete

Example: Make a book viewable by everyone, but only editable by Admins.

Comments

Enable discussions on pages:

1. Settings → Features
2. Enable Page Comments
3. Users can now comment at bottom of pages
4. Useful for feedback and questions

Webhooks

Trigger actions when content changes:

1. Settings → Webhooks
2. + Create New Webhook
3. Name: “Slack Notifications”
4. Endpoint URL: Your webhook URL
5. Events: Select triggers (page created, updated, deleted)
6. Save

Use cases:

• Notify Slack/Discord when docs are updated
• Trigger CI/CD pipeline when docs change
• Sync to external systems

API Access

BookStack has a full REST API:

1. My Account → API Tokens
2. Create Token
3. Name: “Automation Script”
4. Copy token ID and secret
5. Use in scripts for automation

Example API call:

curl -H "Authorization: Token YOUR_TOKEN_ID:YOUR_TOKEN_SECRET" \
  https://bookstack.yourdomain.com/api/books

Customization

Change Theme

1. Settings → Customization
2. Custom HTML Head Content:

<style>
  /* Custom CSS */
  :root {
    --color-primary: #2563eb;
    --color-link: #3b82f6;
  }
</style>

3. Save

Enable Dark Mode

Built-in dark mode:

1. Click profile icon
2. Toggle Dark Mode
3. Saved per user

Custom Homepage

1. Create a page with your desired homepage content
2. Settings → Customization
3. Custom Home Page: Select your page
4. Save

Add Custom Footer

1. Settings → Customization
2. Custom HTML Head Content:

<script>
  // Add custom footer text
  document.addEventListener('DOMContentLoaded', function() {
    const footer = document.querySelector('footer');
    if (footer) {
      footer.innerHTML += '<p>Custom footer text</p>';
    }
  });
</script>

Backup and Restore

Backup Strategy

Option 1: Docker Volumes (Recommended)

# Stop containers
docker-compose down

# Backup everything
tar -czf bookstack-backup-$(date +%Y%m%d).tar.gz config/ database/

# Restart
docker-compose up -d

Option 2: Database Export

# Export database
docker exec bookstack_db mysqldump -u bookstack -pYOUR_PASSWORD bookstackapp > bookstack-db-$(date +%Y%m%d).sql

# Backup uploads
tar -czf bookstack-files-$(date +%Y%m%d).tar.gz config/www/uploads/

Automated Backups

Create backup script at ~/bookstack/backup.sh:

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

mkdir -p $BACKUP_DIR

# Database backup
docker exec bookstack_db mysqldump -u bookstack -pYOUR_PASSWORD bookstackapp | gzip > $BACKUP_DIR/db-$DATE.sql.gz

# Files backup
tar -czf $BACKUP_DIR/files-$DATE.tar.gz -C ~/bookstack config/www/uploads/

# Keep only last 7 days
find $BACKUP_DIR -type f -mtime +7 -delete

echo "Backup completed: $DATE"

Make executable and add to cron:

chmod +x ~/bookstack/backup.sh
crontab -e

Add line:

Restore from Backup

Restore full backup:

docker-compose down
rm -rf config/ database/
tar -xzf bookstack-backup-YYYYMMDD.tar.gz
docker-compose up -d

Restore database only:

docker exec -i bookstack_db mysql -u bookstack -pYOUR_PASSWORD bookstackapp < bookstack-db-YYYYMMDD.sql

Security Best Practices

1. Use HTTPS

Set up a reverse proxy with SSL:

Nginx Proxy Manager or Caddy:

• Point docs.yourdomain.com to http://bookstack:80
• Enable SSL with Let’s Encrypt
• Update APP_URL in docker-compose.yml to https://docs.yourdomain.com

2. Strong Passwords

• Change default admin credentials
• Enforce strong password policy: Settings → Security
• Use unique passwords for database

3. Two-Factor Authentication

Enable 2FA:

1. My Account → Security
2. Setup Multi-Factor Authentication
3. Scan QR code with authenticator app (Authy, Google Authenticator)
4. Enter code to confirm
5. Save backup codes

4. Disable Public Registration

Settings → Registration → Disable Public Registration

5. Regular Updates

cd ~/bookstack
docker-compose pull
docker-compose up -d

6. Audit Logs

Settings → Audit Log shows all actions (views, edits, deletes)

Troubleshooting

Can’t Access BookStack

1. Check containers are running:

docker ps

2. Check logs:

docker logs bookstack
docker logs bookstack_db

3. Verify port isn’t blocked:

sudo ufw allow 8080

Database Connection Errors

1. Verify database credentials match in both services
2. Check database is ready:

docker exec bookstack_db mysql -u bookstack -pYOUR_PASSWORD -e "SHOW DATABASES;"

3. Restart containers:

docker-compose restart

Images Not Uploading

1. Check storage permissions:

docker exec bookstack ls -la /config/www/uploads

2. Increase PHP upload limit (create .env file):

3. Restart BookStack:

docker-compose restart bookstack

Slow Performance

1. Increase allocated resources in docker-compose:

bookstack:
  deploy:
    resources:
      limits:
        memory: 2G

2. Optimize database:

docker exec bookstack_db mysql -u root -pYOUR_ROOT_PASSWORD -e "OPTIMIZE TABLE bookstackapp.*;"

Integrations

LDAP/Active Directory

Connect BookStack to existing user directory:

1. Settings → Authentication
2. Enable LDAP Authentication
3. Configure:
   • Server: ldap://your-server.com
   • Base DN: dc=example,dc=com
   • User filter: (&(uid={user}))
4. Test and save

SAML2 SSO

For enterprise single sign-on:

Edit .env in config folder, add:

Slack/Discord Webhooks

Already covered in Webhooks section above.

Comparison: BookStack vs Alternatives

Choose BookStack if: You want intuitive structure, beautiful interface, and don’t need real-time collaboration.

Choose Outline if: You need Slack-like collaboration and modern team features.

Choose Wiki.js if: You want maximum flexibility and customization.

Choose Docusaurus if: You’re documenting code and want Git-based workflow.

Conclusion

BookStack is the sweet spot for self-hosted documentation—simple enough for anyone to use, powerful enough for serious documentation needs, and beautiful out of the box.

Whether you’re documenting your home lab, building a company wiki, or organizing research notes, BookStack makes it easy to create, find, and share knowledge.

Next Steps:

• Set up BookStack following this guide
• Create your first book and pages
• Configure permissions for your team
• Set up automated backups
• Consider pairing with Nextcloud for file storage

Happy documenting! 📚🚀