Wiki Management¶

This section covers the management, deployment, and maintenance of the brennan.page wiki, including lessons learned about proper repository structure and deployment procedures.

Overview¶

The brennan.page wiki is a MkDocs-based documentation site that provides comprehensive documentation for the homelab infrastructure. It serves as both technical documentation and operational reference.

Architecture¶

Technology Stack¶

• Static Site Generator: MkDocs with Material theme
• Content Format: Markdown files
• Deployment: Built static files served by Caddy
• Location: /opt/homelab/wiki/ on server

Directory Structure¶

Local Repository:

brennan.page/
├── wiki/
│   ├── mkdocs.yml              # MkDocs configuration
│   ├── docs/                   # Markdown content
│   │   ├── index.md           # Main landing page
│   │   ├── services/          # Service documentation
│   │   ├── infrastructure/    # Infrastructure docs
│   │   ├── operations/        # Operational procedures
│   │   ├── configuration/     # Configuration docs
│   │   ├── troubleshooting/   # Troubleshooting guides
│   │   └── reference/         # Reference materials
│   └── deploy-wiki.sh         # Deployment script

Server Structure:

/opt/homelab/wiki/
├── (built static files)       # Generated by MkDocs
└── (source files)             # For local development

Deployment Procedures¶

Local Development¶

1. Install Dependencies:

   pip install mkdocs mkdocs-material
   pip install mkdocs-git-revision-date-localized-plugin
   pip install mkdocs-minify-plugin
   

2. Local Development Server:

   cd wiki/
   mkdocs serve
   # Access at http://localhost:8000
   

3. Build Static Site:

   mkdocs build --clean
   

Server Deployment¶

1. Sync Source Files:

   rsync -avz --exclude '.git' wiki/ root@159.203.44.169:/opt/homelab/wiki/
   

2. Build on Server:

   ssh root@159.203.44.169
   cd /opt/homelab/wiki
   ~/.local/bin/mkdocs build --clean
   

3. Deploy to Web Directory:

   rsync -avz --delete site/ /opt/homelab/wiki/
   

Automated Deployment Script¶

The deploy-wiki.sh script automates the deployment process:

#!/bin/bash
# Build and deploy wiki to server

echo "Building wiki..."
mkdocs build --clean

echo "Deploying to server..."
rsync -avz --delete site/ root@159.203.44.169:/opt/homelab/wiki/

echo "Wiki deployed successfully!"

Configuration¶

MkDocs Configuration (mkdocs.yml)¶

Key configuration elements:

site_name: brennan.page Wiki
site_url: https://wiki.brennan.page

theme:
  name: material
  features:
    - navigation.instant
    - navigation.tracking
    - navigation.tabs
    - navigation.sections
    - search.highlight
    - content.code.copy

plugins:
  - search
  - git-revision-date-localized
  - minify

nav:
  - Home: index.md
  - Services: services/index.md
  - Infrastructure: infrastructure/index.md
  - Operations: operations/index.md
  - Configuration: configuration/index.md
  - Troubleshooting: troubleshooting/index.md
  - Reference: reference/index.md

Caddy Configuration¶

The wiki is served by Caddy with this configuration:

wiki.brennan.page {
    import compression
    import security

    root * /opt/homelab/wiki
    file_server
    handle_errors {
        respond "Error 404: Wiki page not found" 404
    }
}

Content Organization¶

Service-Based Structure¶

The wiki uses a service-based organization rather than phase-based:

• Infrastructure Services: Caddy, PostgreSQL, MariaDB
• Management Services: Portainer, FileBrowser, Monitor
• Productivity Services: Vikunja, HedgeDoc, Linkding, Navidrome
• Content & Community Services: WriteFreely, Flarum, FreshRSS

Documentation Standards¶

Each service page includes: - Configuration: Docker compose and environment variables - Management: Admin interfaces and common operations - Database: Schema and management commands - Performance: Resource usage and optimization - Security: Access control and best practices - Troubleshooting: Common issues and solutions - Backup: Backup and recovery procedures

Lessons Learned¶

Repository Structure¶

Critical Lesson: Follow the spec sheet directory structure exactly.

Correct Structure: - Server: /opt/homelab/wiki/ for built files - Local: brennan.page/wiki/ for source files - Never: Move files out of the main repository

Common Mistakes: - ❌ Moving files to temporary folders - ❌ Using /var/www/wiki/ instead of /opt/homelab/wiki/ - ❌ Creating separate repositories for components

File Management¶

Best Practices: - Always COPY files, never MOVE when restructuring - Verify Git status before and after operations - Keep source files in the main repository - Use rsync for server deployments

Recovery Procedures:

# If files are accidentally moved
mv /path/to/moved/files ./original/location/
git status  # Verify what changed
git add .   # Stage changes
git commit -m "Restore moved files"

Deployment Issues¶

Common Problems:

1. 404 Errors After Deployment
2. Check Caddy configuration path
3. Verify files are in /opt/homelab/wiki/

4. Restart Caddy if needed

5. Build Failures

6. Install missing MkDocs plugins
7. Check mkdocs.yml syntax

8. Verify all referenced files exist

9. Navigation Issues

10. Update mkdocs.yml navigation section
11. Ensure all referenced files exist
12. Check for broken links

Performance Optimization¶

Build Optimization:

# Use clean builds to avoid stale files
mkdocs build --clean

# Enable minification for production
plugins:
  - minify:
      minify_html: true

Serving Optimization: - Enable compression in Caddy - Use appropriate cache headers - Monitor build times

Maintenance¶

Regular Tasks¶

Daily: - Monitor wiki accessibility - Check for broken links - Verify deployment success

Weekly: - Update MkDocs and plugins - Review content for accuracy - Check search functionality

Monthly: - Audit content structure - Review navigation organization - Update service documentation

Content Updates¶

Adding New Services: 1. Create service documentation in wiki/docs/services/ 2. Update wiki/docs/services/index.md 3. Update navigation in mkdocs.yml 4. Build and deploy

Updating Existing Services: 1. Update relevant markdown files 2. Verify all links work 3. Update service status tables 4. Build and deploy

Backup and Recovery¶

Backup Source Files:

# Backup wiki source
tar czf wiki-backup-$(date +%Y%m%d).tar.gz wiki/

# Backup built files
tar czf wiki-built-backup-$(date +%Y%m%d).tar.gz /opt/homelab/wiki/

Recovery Procedures:

# Restore from backup
tar xzf wiki-backup-YYYYMMDD.tar.gz
mkdocs build --clean
rsync -avz --delete site/ /opt/homelab/wiki/

Troubleshooting¶

Common Issues¶

Wiki Not Accessible:

# Check Caddy status
docker ps | grep caddy

# Check wiki files
ls -la /opt/homelab/wiki/

# Check Caddy logs
docker logs caddy --tail 20

Build Errors:

# Check MkDocs version
mkdocs --version

# Check for missing plugins
pip list | grep mkdocs

# Rebuild with verbose output
mkdocs build --verbose

Navigation Problems:

# Validate mkdocs.yml
mkdocs build --quiet

# Check for missing files
find docs/ -name "*.md" | sort

Performance Issues¶

Slow Build Times: - Reduce number of large images - Optimize markdown files - Check for circular references

Slow Load Times: - Enable compression - Optimize images - Review plugin usage

Integration¶

Git Workflow¶

Commit Changes:

git add wiki/
git commit -m "Update wiki documentation"
git push origin main

Deployment Workflow: 1. Make changes locally 2. Test with mkdocs serve 3. Commit changes to Git 4. Deploy to server 5. Verify deployment

CI/CD Integration¶

Automated Deployment:

# Example GitHub Actions
- name: Deploy Wiki
  run: |
    mkdocs build --clean
    rsync -avz --delete site/ root@server:/opt/homelab/wiki/

Monitoring¶

Health Checks:

# Check wiki accessibility
curl -f https://wiki.brennan.page/

# Check specific pages
curl -f https://wiki.brennan.page/services/

# Monitor response times
curl -w "Response time: %{time_total}s" https://wiki.brennan.page/

Security¶

Access Control¶

Wiki Security: - Public read access - No authentication required - Served over HTTPS only

Source Security: - Git repository with access control - No sensitive data in source files - Environment variables for secrets

Content Security¶

Markdown Security: - Sanitize user input - Validate external links - Review uploaded content

Build Security: - Use trusted MkDocs plugins - Regular updates to dependencies - Scan for vulnerabilities

References¶

• MkDocs Documentation
• Material Theme
• Caddy Server
• Git Workflow
• SSH Commands