Documentation Build System¶

This page describes the automated documentation build system for the VPN Exit Controller project.

Overview¶

The VPN Exit Controller documentation is built using MkDocs with the Material theme and is automatically rebuilt whenever changes are pushed to the repository. The documentation is hosted at https://vpn-docs.rbnk.uk.

Architecture¶

graph LR
    A[Git Push] --> B[Gitea Webhook]
    B --> C[Webhook Server<br/>Port 8888]
    C --> D[Rebuild Script]
    D --> E[Docker Build]
    E --> F[New Container]
    F --> G[Traefik]
    G --> H[vpn-docs.rbnk.uk]

Components¶

1. MkDocs Site¶

Location: /opt/vpn-exit-controller/mkdocs-site/

The documentation source includes:

• mkdocs.yml - MkDocs configuration
• docs/ - Documentation source files
• Dockerfile - Multi-stage build for documentation
• docker-compose.yml - Container orchestration
• nginx.conf - Web server configuration

2. Webhook Server¶

Script: /opt/vpn-exit-controller/scripts/webhook-docs-rebuild.py
Service: docs-webhook.service
Port: 8888

The webhook server:

• Listens for POST requests to /rebuild-docs
• Validates webhook signatures (optional)
• Triggers the rebuild script
• Logs all activity

3. Rebuild Script¶

Location: /opt/vpn-exit-controller/scripts/rebuild-docs.sh

The rebuild script performs:

1. Stops the existing documentation container
2. Builds a new container with latest documentation
3. Starts the new container
4. Verifies deployment success
5. Logs the rebuild event

4. Docker Container¶

Container Name: vpn-docs
Internal Port: 80
External Port: 8001

The container uses a multi-stage build:

1. Builder stage: Python environment with MkDocs
2. Production stage: Nginx serving static files

Configuration¶

Webhook Service Configuration¶

The webhook service is managed by systemd:

[Unit]
Description=Documentation Rebuild Webhook Server
After=network.target docker.service
Requires=docker.service

[Service]
Type=simple
User=root
WorkingDirectory=/opt/vpn-exit-controller
Environment="WEBHOOK_SECRET=change-me-to-secure-secret"
ExecStart=/usr/bin/python3 /opt/vpn-exit-controller/scripts/webhook-docs-rebuild.py
Restart=always
RestartSec=10

Gitea Webhook Setup¶

To configure automatic rebuilds:

1. Navigate to your repository settings in Gitea
2. Go to Webhooks section
3. Add a new webhook with:
4. URL: http://10.10.10.20:8888/rebuild-docs
5. Method: POST
6. Events: Push events
7. Secret: (optional but recommended)

Security Configuration¶

For production use, configure a webhook secret:

1. Generate a secure secret:

   openssl rand -hex 32
   

2. Update the systemd service:

   systemctl edit docs-webhook
   

3. Add the environment variable:

   [Service]
   Environment="WEBHOOK_SECRET=your-generated-secret"
   

4. Use the same secret in Gitea webhook configuration

Usage¶

Automatic Builds¶

Documentation is automatically rebuilt when:

• Code is pushed to the main branch
• A webhook request is received
• The rebuild is manually triggered

Manual Rebuild¶

To manually rebuild documentation:

# Option 1: Direct script execution
/opt/vpn-exit-controller/scripts/rebuild-docs.sh

# Option 2: Trigger via webhook
curl -X POST http://localhost:8888/rebuild-docs

# Option 3: With webhook secret
curl -X POST http://localhost:8888/rebuild-docs \
  -H "X-Hub-Signature-256: sha256=your-signature"

Monitoring¶

Check the system status:

# Webhook service status
systemctl status docs-webhook

# Container status
docker ps | grep vpn-docs

# Recent rebuilds
tail -f /opt/vpn-exit-controller/logs/docs-rebuild.log

# Webhook activity
tail -f /opt/vpn-exit-controller/logs/webhook.log

Troubleshooting¶

Common Issues¶

Webhook Not Triggering¶

1. Check service status:

   systemctl status docs-webhook
   journalctl -u docs-webhook -f
   

2. Test webhook connectivity:

   curl -X POST http://localhost:8888/rebuild-docs
   

3. Verify Gitea can reach the webhook URL

Build Failures¶

1. Check Docker logs:

   docker logs vpn-docs
   

2. Manually test the build:

   cd /opt/vpn-exit-controller/mkdocs-site
   docker-compose build
   

3. Check disk space:

   df -h
   

Site Not Accessible¶

1. Verify container health:

   docker inspect vpn-docs --format='{{.State.Health.Status}}'
   

2. Check Traefik routing:

   docker logs traefik | grep vpn-docs
   

3. Test SSL certificate:

   curl -vI https://vpn-docs.rbnk.uk
   

Log Locations¶

• Webhook logs: /opt/vpn-exit-controller/logs/webhook.log
• Rebuild logs: /opt/vpn-exit-controller/logs/docs-rebuild.log
• Container logs: docker logs vpn-docs
• Service logs: journalctl -u docs-webhook

Maintenance¶

Regular Tasks¶

• Monitor disk usage - Documentation builds can consume space
• Review logs - Check for failed builds or security issues
• Update dependencies - Keep MkDocs and plugins updated
• Rotate logs - Ensure log files don't grow too large

Updates¶

To update the documentation system:

1. Update MkDocs dependencies:

   cd /opt/vpn-exit-controller/mkdocs-site
   # Update requirements.txt
   docker-compose build --no-cache
   

2. Update webhook server:

   # Modify the Python script
   systemctl restart docs-webhook
   

Performance¶

The documentation build process:

• Takes 1-2 minutes to complete
• Uses minimal CPU during normal operation
• Requires ~500MB disk space for build cache
• Serves static files efficiently via Nginx

Security Considerations¶

1. Webhook Authentication: Always use a secret in production
2. Network Access: Limit webhook access to trusted sources
3. Container Isolation: Runs with minimal privileges
4. SSL/TLS: All public access uses HTTPS via Traefik
5. Input Validation: Webhook server validates all inputs

Future Enhancements¶

Potential improvements to consider:

• Add build status badges
• Implement build notifications
• Add search analytics
• Enable documentation versioning
• Add automated link checking
• Implement A/B testing for docs
• Add user feedback collection

Related Documentation¶

• Deployment Guide - Overall system deployment
• Maintenance Guide - System maintenance procedures
• Troubleshooting Guide - General troubleshooting