# 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
```bash
docker ps | grep bookstack
```

Expected output:
```
bookstack       Up X hours
bookstack_db    Up X hours
```

### HTTP Check
```bash
curl -I http://localhost:6875
```

Expected: `200 OK` or `302 Found`

### API Check
```bash
curl -s -H "Authorization: Token jpipe2-c33b96497a61ca91:100527aa211096463db2f775c9a267c816d11d54b1ec3e038b2b41ee2ae6c6c4" http://localhost:6875/api/docs.json | head -5
```

Expected: JSON response with API docs.

### Database Check
```bash
docker exec bookstack_db mysql -u bookstack -pB4s1cAS_w1k1_2026! bookstackapp -e "SELECT count(*) FROM pages;"
```

---

## Restart Procedure

### Quick Restart (Container Only)
```bash
docker restart bookstack
```

### Full Stack Restart (Container + Database)
```bash
cd ~/system/services/bookstack
docker compose down
docker compose up -d
```

Wait 30 seconds, then verify:
```bash
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
```bash
node ~/system/tools/bookstack-sync.js sync
```

### Sync Single File
```bash
node ~/system/tools/bookstack-sync.js sync ~/system/rules/development.md
```

### Check Sync Status
```bash
node ~/system/tools/bookstack-sync.js status
```

### Force Overwrite All
```bash
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:**
```bash
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:**
```bash
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:**
```bash
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:**
```bash
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:**
```bash
curl -I http://localhost:6875
```

**Check API endpoint:**
```bash
curl -s -H "Authorization: Token jpipe2-c33b96497a61ca91:100527aa211096463db2f775c9a267c816d11d54b1ec3e038b2b41ee2ae6c6c4" http://localhost:6875/api/shelves | head -20
```

**Check logs:**
```bash
docker logs bookstack --tail 100
```

### Problem: Database connection issues
**Check database health:**
```bash
docker exec bookstack_db mysqladmin -u bookstack -pB4s1cAS_w1k1_2026! ping
```

Expected: `mysqld is alive`

**Check connection settings:**
```bash
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
```bash
curl -s -H "Authorization: Token jpipe2-c33b96497a61ca91:100527aa211096463db2f775c9a267c816d11d54b1ec3e038b2b41ee2ae6c6c4" http://localhost:6875/api/shelves
```

### List Books
```bash
curl -s -H "Authorization: Token jpipe2-c33b96497a61ca91:100527aa211096463db2f775c9a267c816d11d54b1ec3e038b2b41ee2ae6c6c4" http://localhost:6875/api/books
```

### List Pages
```bash
curl -s -H "Authorization: Token jpipe2-c33b96497a61ca91:100527aa211096463db2f775c9a267c816d11d54b1ec3e038b2b41ee2ae6c6c4" http://localhost:6875/api/pages
```

### Create Page
```bash
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
```bash
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)
```bash
cd ~/system/services/bookstack
tar -czf ~/backups/bookstack-data-$(date +%Y%m%d-%H%M%S).tar.gz data/
```

### Restore from Backup
```bash
# 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)