MBPanel Documentation Hosting Guide¶

Quick Setup¶

1. Update Nginx Configuration¶

Copy the provided nginx configuration and update paths:

# Copy nginx config from docs directory
sudo cp docs/nginx-docs.conf /etc/nginx/sites-available/mbpanel-docs

# Update paths in the config
sudo nano /etc/nginx/sites-available/mbpanel-docs

Important changes needed: - server_name: Set to your actual domain - root: Set to actual path where you'll deploy docs - SSL paths if using HTTPS

2. Enable Site¶

# Enable the site
sudo ln -s /etc/nginx/sites-available/mbpanel-docs /etc/nginx/sites-enabled/

# Test configuration
sudo nginx -t

# Reload nginx
sudo systemctl reload nginx

3. Deploy Documentation¶

# Using the deployment script
./scripts/deploy-docs.sh deploy

# Or manually:
mkdocs build
sudo cp -r site/* /var/www/mbpanel-docs/
sudo chown -R www-data:www-data /var/www/mbpanel-docs/

Advanced Configuration¶

SSL/HTTPS Setup¶

Get SSL Certificate:

# Using Let's Encrypt
sudo certbot --nginx -d mbpanel-docs.yourdomain.com

Update nginx config to uncomment HTTPS section

Performance Optimization¶

The nginx config includes: - Gzip compression for faster loading - Static asset caching (1 year for CSS/JS/images) - Security headers for protection

Semantic Search API¶

If you want to enable semantic search in the web interface:

Ensure Qdrant is running:
```
docker compose ps qdrant
```

Build semantic index:

python3 -m tools.docs.cli semantic-index

Add API proxy to nginx:

# Add this to your server block
location /api/v1/docs/ {
    proxy_pass http://localhost:8000;
    proxy_set_header Host $host;
    proxy_set_header X-Real-IP $remote_addr;
}

Deployment Options¶

Option 1: Static Hosting (Recommended)¶

Pros: Fast, secure, simple
Cons: No dynamic features
Use for: Production documentation

Option 2: Dynamic with API¶

Pros: Semantic search, dynamic features
Cons: More complex, requires backend
Use for: Development/internal docs

Option 3: Docker Deployment¶

FROM nginx:alpine
COPY site/ /usr/share/nginx/html/
COPY docs/nginx-docs.conf /etc/nginx/conf.d/default.conf

Monitoring¶

Nginx Logs¶

# Access logs
sudo tail -f /var/log/nginx/mbpanel-docs-access.log

# Error logs
sudo tail -f /var/log/nginx/mbpanel-docs-error.log

Health Check¶

Add to your nginx config:

location /health {
    access_log off;
    return 200 "OK\n";
    add_header Content-Type text/plain;
}

Troubleshooting¶

404 Errors¶

Check file permissions: ls -la /var/www/mbpanel-docs/
Verify nginx config: sudo nginx -t
Check nginx error logs

Permission Issues¶

# Fix ownership
sudo chown -R www-data:www-data /var/www/mbpanel-docs/
sudo chmod -R 755 /var/www/mbpanel-docs/

Build Issues¶

# Clean build
rm -rf site/
mkdocs build --clean --strict

CI/CD Integration¶

GitHub Actions Workflow¶

The project uses .github/workflows/deploy-docs.yml for automated documentation deployment.

Branch Strategy: - main → Production deployment (atomic with rollback) - dev-* (e.g., dev-tony, dev-feature) → Staging deployment - Pull requests → Preview deployments

Required GitHub Secrets:

For Staging: - STAGING_HOST - Staging server hostname - STAGING_USER - SSH username - STAGING_SSH_KEY - Private SSH key (no passphrase) - STAGING_PATH - Deployment path (e.g., /var/www/mbpanel-docs-staging) - STAGING_URL - Full URL for health checks

For Production: - PRODUCTION_HOST - Production server hostname - PRODUCTION_USER - SSH username - PRODUCTION_SSH_KEY - Private SSH key (no passphrase) - PRODUCTION_PATH - Deployment path (e.g., /var/www/mbpanel-docs) - PRODUCTION_URL - Full URL for health checks

Deployment Features: - Atomic deployment with temporary __new__ directory - Automatic rollback on failure (keeps last 5 backups) - Health checks via HTTP curl - PR preview deployments

Manual Deployment:

# Local build and deploy
mkdocs build
./scripts/deploy-docs.sh deploy

# Build semantic search index (local only, not in CI)
python3 -m tools.docs.cli semantic-index --force

Security Considerations¶

Disable directory listing: Already configured
Use HTTPS: Strongly recommended for production
Rate limiting: Consider for API endpoints
Regular updates: Keep nginx and dependencies updated

Performance Tips¶

Enable HTTP/2: Included in HTTPS config
Use CDN: For global distribution
Optimize images: Use WebP format
Minimize assets: Already handled by MkDocs Material

Backup Strategy¶

The deployment script automatically creates backups before deployment:

# Manual backup
sudo cp -r /var/www/mbpanel-docs /var/www/mbpanel-docs-backup-$(date +%Y%m%d)

# Restore from backup
./scripts/deploy-docs.sh restore