BookStack Runbook

Last Verified: 2026-02-17 | Owner: John 
 
 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: jpipe2-c33b96497a61ca91 
 Token Secret: 100527aa211096463db2f775c9a267c816d11d54b1ec3e038b2b41ee2ae6c6c4 
 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 jpipe2-c33b96497a61ca91:100527aa211096463db2f775c9a267c816d11d54b1ec3e038b2b41ee2ae6c6c4" http://localhost:6875/api/docs.json | head -5
 
 Expected: JSON response with API docs. 
 Database Check 
 docker exec bookstack_db mysql -u bookstack -pB4s1cAS_w1k1_2026! 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: 
 
 Database not ready - wait 30s and retry 
 Port 6875 already bound - check lsof -i :6875 
 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: 
 
 Login to BookStack 
 Go to Settings → API Tokens 
 Create new token 
 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 jpipe2-c33b96497a61ca91:100527aa211096463db2f775c9a267c816d11d54b1ec3e038b2b41ee2ae6c6c4" 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 mysqladmin -u bookstack -pB4s1cAS_w1k1_2026! 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=B4s1cAS_w1k1_2026!
DB_DATABASE=bookstackapp
 
 
 API Usage 
 List Shelves 
 curl -s -H "Authorization: Token jpipe2-c33b96497a61ca91:100527aa211096463db2f775c9a267c816d11d54b1ec3e038b2b41ee2ae6c6c4" http://localhost:6875/api/shelves
 
 List Books 
 curl -s -H "Authorization: Token jpipe2-c33b96497a61ca91:100527aa211096463db2f775c9a267c816d11d54b1ec3e038b2b41ee2ae6c6c4" http://localhost:6875/api/books
 
 List Pages 
 curl -s -H "Authorization: Token jpipe2-c33b96497a61ca91:100527aa211096463db2f775c9a267c816d11d54b1ec3e038b2b41ee2ae6c6c4" http://localhost:6875/api/pages
 
 Create Page 
 curl -X POST -H "Authorization: Token jpipe2-c33b96497a61ca91:100527aa211096463db2f775c9a267c816d11d54b1ec3e038b2b41ee2ae6c6c4" \
 -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 mysqldump -u bookstack -pB4s1cAS_w1k1_2026! 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 mysql -u bookstack -pB4s1cAS_w1k1_2026! 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)