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: admin@admin.com
• 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: admin@admin.com / 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=admin@admin.com --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)