Posted inHomeLab

Stop Guessing Your Configs: Building a Professional HomeLab Wiki with BookStack

HomeLab tutorial - IT technology blog
HomeLab tutorial - IT technology blog

The 2:15 AM Reality Check

It’s late. My main Proxmox node just threw a kernel panic, and the local DNS is down. I’m staring at a terminal, trying to remember if I assigned the recovery bridge to VLAN 10 or 20. I’m digging through a messy notes.txt file on my laptop that hasn’t been updated in 14 months, cursing my past self for being lazy with documentation.

If you’ve run a HomeLab for more than a week, you know this frustration. We build complex systems but treat documentation as an afterthought. After years of breaking things, I’ve realized that a centralized, searchable Wiki isn’t a luxury—it’s the backbone of a stable lab. Without it, you aren’t running a HomeLab; you’re managing a house of cards that will eventually collapse.

Choosing a Documentation Strategy

I’ve tried almost every method to track my lab configurations. Here is how the most common strategies actually perform in a crisis.

The Flat File Approach (Markdown & Git)

Many engineers prefer keeping Markdown files in a Git repo. It’s portable and version-controlled, which is great for code. However, it fails when you need to share a quick guide with a family member who doesn’t use VS Code. Searching through 50+ nested directories in a terminal while your network is offline is a recipe for a headache.

The Cloud Approach (Notion/Confluence)

Notion is aesthetically pleasing, and Confluence is the corporate standard. But there is a major flaw: privacy and availability. I don’t want my internal IP schemes or SSH keys sitting on a third-party server. More importantly, if your internet goes down, your documentation vanishes exactly when you need it to fix the gateway.

The BookStack Solution

BookStack strikes the right balance. It uses a simple library metaphor: Shelves > Books > Chapters > Pages. It is self-hosted, lightweight, and features a search engine that actually finds what you need. It supports both Markdown and a WYSIWYG editor, making it accessible even when you aren’t in a “developer” mindset.

Why BookStack Works

The Strengths

  • Logical Hierarchy: The Shelf/Book system prevents the “infinite folder” problem. I use a “Networking” shelf for switch configs and a “Servers” shelf for hardware specs.
  • Low Friction Backups: The entire system consists of a MySQL database and an image folder. You can automate the backup process with a five-line script.
  • Native Draw.io Integration: You can embed network diagrams directly into your pages. This is indispensable for documenting rack wiring or complex Docker networks.
  • Granular Permissions: You can give family members “Read Only” access to the Plex guide while keeping your root password book restricted to your admin account.

The Trade-offs

  • Fixed Structure: BookStack forces you into its hierarchy. If you prefer a completely flat or networked (Zettelkasten) structure, you might find it restrictive.
  • Database Reliance: Unlike flat files, if your database becomes corrupted and you lack a backup, your documentation is gone.

The Recommended Deployment

I always recommend running BookStack inside Docker. This isolates the PHP dependencies from your host OS and makes hardware migrations simple. We will use a docker-compose setup with two containers: the BookStack app and a MariaDB database.

Step 1: Create the Directory Structure

First, set up a dedicated space for your Wiki data. I usually host mine in /opt/bookstack.

mkdir -p ~/homelab/bookstack/config
mkdir -p ~/homelab/bookstack/db_data
cd ~/homelab/bookstack

Step 2: The Docker Compose Configuration

Create a docker-compose.yml file. We are using the images from linuxserver.io because they provide consistent updates and excellent documentation for HomeLab users.

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://192.168.1.50:6875 # Use your static server IP
      - DB_HOST=bookstack_db
      - DB_USER=bookstack
      - DB_PASS=UseAStrongPasswordHere
      - DB_DATABASE=bookstackapp
    volumes:
      - ./config:/config
    ports:
      - 6875: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=YourRootPassword
      - MYSQL_DATABASE=bookstackapp
      - MYSQL_USER=bookstack
      - MYSQL_PASSWORD=UseAStrongPasswordHere
    volumes:
      - ./db_data:/config
    restart: unless-stopped

Technical Note: Ensure the APP_URL matches the exact IP or DNS name you’ll use. If this is incorrect, BookStack will fail to load CSS and JavaScript, leaving you with a broken, text-only page.

Step 3: Booting Up

Launch the stack with a single command:

docker compose up -d

Wait about 30 seconds for the database to initialize. You can monitor the progress by running docker logs -f bookstack.

Step 4: Initial Security

Access the interface at http://your-server-ip:6875. The default login is [email protected] with the password password. Change these immediately. In a HomeLab, your Wiki contains the blueprints to your entire digital life. Secure it as you would your password manager.

Organizing for a Crisis

Don’t just dump raw text into pages. Use BookStack’s structure to create a functional map. Here is a 3-tier setup that works well for most labs:

  1. Shelf: Infrastructure
    • Book: Networking (VLAN IDs, 24-port switch mapping, Firewall rules)
    • Book: Virtualization (Node IPs, shared storage mount points)
  2. Shelf: Services
    • Book: Media (Plex libraries, Docker compose snippets)
    • Book: Automation (Home Assistant entities, Zigbee channel maps)
  3. Shelf: Maintenance
    • Book: Disaster Recovery (The literal “Step 1, Step 2” to restore from backups)

The Final Step: Automated Backups

A Wiki without a backup is a liability. Since we are using Docker, we can easily dump the database and compress the config folder. I run this script via a cron job every night at 3 AM:

#!/bin/bash
# BookStack Backup Script
BACKUP_DIR="/mnt/nas/backups/bookstack"
DATE=$(date +%Y-%m-%d)

# Export the database
docker exec bookstack_db /usr/bin/mariadb-dump -u bookstack -pUseAStrongPasswordHere bookstackapp > $BACKUP_DIR/db_$DATE.sql

# Compress config and images
tar -czf $BACKUP_DIR/files_$DATE.tar.gz ~/homelab/bookstack/config

# Prune backups older than 14 days
find $BACKUP_DIR -type f -mtime +14 -delete

Setting this up takes 20 minutes, but it will save you hours of rebuilding. The next time your lab goes dark, you won’t be guessing. You’ll open BookStack, find the guide you wrote six months ago, and fix the issue in minutes. That is how you move from being a hobbyist to a pro admin.

Share:
Tags: