Skip to main content

BookStack Runbook

Runbook: BookStack

Service Type: Wiki / Knowledge Base Container: bookstack (lscr.io/linuxserver/bookstack:latest) Ports: 6875 (external) → 80 (internal) Internal URL: http://localhost:6875 External URL: http://192.168.68.61:6875 (LAN only, no Cloudflare tunnel yet) Database: MariaDB (bookstack_db) Compose File: ~/system/services/bookstack/docker-compose.yml

Service Info

BookStack is the documentation wiki for BasicAS Group. Stores runbooks, system docs, org info.

Stack:

  • bookstack - Main app (LinuxServer.io build)
  • bookstack_db - MariaDB (LinuxServer.io build)

Access:

  • Admin URL: http://localhost:6875 or http://192.168.68.61:6875
  • Admin Email: [email protected]
  • Admin Password: password
  • WARNING: Default admin credentials! Change immediately after first login.

API:

  • Token ID: alai-v2-84c8e63775a52492
  • Token Secret: ff80c10c7c881d5dbf341500b3e826309a8570a11277d887143305d975b076de
  • Config: ~/system/config/bookstack.json
  • Sync Tool: node ~/system/tools/bookstack-sync.js sync

Status Check

Container Health

docker ps | grep bookstack

Expected output:

bookstack       Up X hours
bookstack_db    Up X hours

HTTP Check

curl -I http://localhost:6875

Expected: 200 OK or 302 Found

API Check

curl -s -H "Authorization: Token alai-v2-84c8e63775a52492:ff80c10c7c881d5dbf341500b3e826309a8570a11277d887143305d975b076de" http://localhost:6875/api/docs.json | head -5

Expected: JSON response with API docs.

Database Check

docker exec bookstack_db mariadb -u bookstack -p'8CdydCxVBD7wBoCVRXZE' bookstackapp -e "SELECT count(*) FROM pages;"

Restart Procedure

Quick Restart (Container Only)

docker restart bookstack

Full Stack Restart (Container + Database)

cd ~/system/services/bookstack
docker compose down
docker compose up -d

Wait 30 seconds, then verify:

docker ps | grep bookstack
curl -I http://localhost:6875

Sync System Docs to BookStack

BookStack is auto-populated from ~/system/ using the sync tool.

Sync All Mapped Content

node ~/system/tools/bookstack-sync.js sync

Sync Single File

node ~/system/tools/bookstack-sync.js sync ~/system/rules/development.md

Check Sync Status

node ~/system/tools/bookstack-sync.js status

Force Overwrite All

node ~/system/tools/bookstack-sync.js push

Mapping File: ~/system/config/bookstack-sync-map.json State File: ~/system/config/bookstack-sync-state.json

Troubleshooting

Problem: Container won't start

Check logs:

docker logs bookstack --tail 100

Common causes:

  1. Database not ready - wait 30s and retry
  2. Port 6875 already bound - check lsof -i :6875
  3. Volume permission issues - check ~/system/services/bookstack/data/

Fix:

cd ~/system/services/bookstack
docker compose down
docker compose up -d bookstack_db
sleep 30
docker compose up -d bookstack

Problem: Can't login (wrong password)

Check if admin credentials were changed in UI:

  • Default: [email protected] / password
  • If changed, use new credentials or reset via database

Reset admin password:

docker exec -it bookstack php /app/www/artisan bookstack:create-admin [email protected] --name=Admin --password=newpassword

Problem: API returns 401 Unauthorized

Check token exists:

cat ~/system/config/bookstack.json

Regenerate token in UI:

  1. Login to BookStack
  2. Go to Settings → API Tokens
  3. Create new token
  4. Update ~/system/config/bookstack.json

Problem: Sync tool fails (500 error)

Check BookStack is running:

curl -I http://localhost:6875

Check API endpoint:

curl -s -H "Authorization: Token alai-v2-84c8e63775a52492:ff80c10c7c881d5dbf341500b3e826309a8570a11277d887143305d975b076de" http://localhost:6875/api/shelves | head -20

Check logs:

docker logs bookstack --tail 100

Problem: Database connection issues

Check database health:

docker exec bookstack_db mariadb-admin -u bookstack -p'8CdydCxVBD7wBoCVRXZE' ping

Expected: mysqld is alive

Check connection settings:

docker exec bookstack env | grep DB_

Expected:

DB_HOST=bookstack_db
DB_PORT=3306
DB_USERNAME=bookstack
DB_PASSWORD=8CdydCxVBD7wBoCVRXZE
DB_DATABASE=bookstackapp

API Usage

List Shelves

curl -s -H "Authorization: Token alai-v2-84c8e63775a52492:ff80c10c7c881d5dbf341500b3e826309a8570a11277d887143305d975b076de" http://localhost:6875/api/shelves

List Books

curl -s -H "Authorization: Token alai-v2-84c8e63775a52492:ff80c10c7c881d5dbf341500b3e826309a8570a11277d887143305d975b076de" http://localhost:6875/api/books

List Pages

curl -s -H "Authorization: Token alai-v2-84c8e63775a52492:ff80c10c7c881d5dbf341500b3e826309a8570a11277d887143305d975b076de" http://localhost:6875/api/pages

Create Page

curl -X POST -H "Authorization: Token alai-v2-84c8e63775a52492:ff80c10c7c881d5dbf341500b3e826309a8570a11277d887143305d975b076de" \
  -H "Content-Type: application/json" \
  -d '{"book_id":1,"name":"Page Title","markdown":"# Content"}' \
  http://localhost:6875/api/pages

Full API docs: http://localhost:6875/api/docs

Dependencies

  • Docker - Service runtime
  • No external dependencies - LAN-only access

Backup

Database Dump

docker exec bookstack_db mariadb-dump -u bookstack -p'8CdydCxVBD7wBoCVRXZE' bookstackapp | gzip > ~/backups/bookstack-$(date +%Y%m%d-%H%M%S).sql.gz

Data Volumes (includes uploads, images)

cd ~/system/services/bookstack
tar -czf ~/backups/bookstack-data-$(date +%Y%m%d-%H%M%S).tar.gz data/

Restore from Backup

# Stop service
cd ~/system/services/bookstack
docker compose down

# Restore database
gunzip -c ~/backups/bookstack-YYYYMMDD-HHMMSS.sql.gz | docker exec -i bookstack_db mariadb -u bookstack -p'8CdydCxVBD7wBoCVRXZE' bookstackapp

# Restore data (if needed)
cd ~/system/services/bookstack
tar -xzf ~/backups/bookstack-data-YYYYMMDD-HHMMSS.tar.gz

# Start service
docker compose up -d

Configuration

Key Environment Variables

  • APP_URL - Public URL (http://192.168.68.61:6875)
  • APP_KEY - Laravel encryption key (base64-encoded)
  • DB_HOST - Database host (bookstack_db)
  • DB_USERNAME - Database user (bookstack)
  • DB_PASSWORD - Database password
  • DB_DATABASE - Database name (bookstackapp)
  • QUEUE_CONNECTION - Job queue driver (database)
  • PUID/PGID - User/group IDs (1000/1000)
  • TZ - Timezone (Europe/Sarajevo)

Full config: ~/system/services/bookstack/docker-compose.yml

Application Settings (via UI)

  • Access: Settings (gear icon, top-right)
  • Customize: Branding, registration, auth, permissions

Content Structure

BookStack organizes content as:

Shelf (top-level category)
  └─ Book (collection of pages)
       └─ Page (markdown document)
            └─ Chapter (optional grouping)

Current structure (as of 2026-02-10):

  • 2 shelves (BasicAS System, Organization)
  • 15 books (System Architecture, Operations, Runbooks, etc.)
  • 43 pages (GOTCHA framework, rules, agent docs, runbooks, etc.)

Notes

  • Admin password: Default is password - MUST be changed!
  • External access: LAN-only (no Cloudflare tunnel) - consider adding tunnel for remote access
  • API token: Stored in plaintext in config file - secure via file permissions (chmod 600)
  • Sync tool: Auto-updates BookStack from ~/system/ markdown files
  • Timezone: Europe/Sarajevo (BiH time)
  • LinuxServer.io build: Community-maintained, not official BookStack image

Last updated: 2026-02-10 Maintained by: John (AI Director)

No comments to display

Back to top