GitHub Actions Setup Guide for MBPanel Documentation

Overview

This GitHub Actions workflow automatically builds and deploys your documentation: - Main branch → Production deployment - Develop branch → Staging deployment - Pull Requests → Preview deployments - Manual triggers → Choose environment

🚀 Setup Instructions

1. Repository Settings

Go to your GitHub repository → Settings → Secrets and variables → Actions

2. Add Repository Secrets

Add these secrets for your deployment configuration:

Production Secrets

PRODUCTION_HOST=your-production-server.com
PRODUCTION_USER=deploy
PRODUCTION_SSH_KEY=(your full OpenSSH private key with BEGIN/END headers)
PRODUCTION_PATH=/var/www/mbpanel-docs
PRODUCTION_URL=https://docs.yourdomain.com

Staging Secrets

STAGING_HOST=your-staging-server.com
STAGING_USER=deploy
STAGING_SSH_KEY=(your full OpenSSH private key with BEGIN/END headers)
STAGING_PATH=/var/www/mbpanel-docs-staging
STAGING_URL=https://staging-docs.yourdomain.com

3. Server Setup

On Your Server(s):

1. Create deployment user:

   sudo useradd -m -s /bin/bash deploy
   sudo usermod -aG sudo deploy
   

2. Setup SSH key:

   # On your local machine
   ssh-keygen -t ed25519 -C "deploy@yourdomain.com" -f ~/.ssh/deploy-key
   
   # Copy public key to server
   ssh-copy-id -i ~/.ssh/deploy-key.pub deploy@your-server.com
   

3. Configure nginx directories:

   # Production
   sudo mkdir -p /var/www/mbpanel-docs/{current,backup}
   sudo chown deploy:deploy /var/www/mbpanel-docs
   
   # Staging
   sudo mkdir -p /var/www/mbpanel-docs-staging/{staging,preview}
   sudo chown deploy:deploy /var/www/mbpanel-docs-staging
   

4. Setup sudoers for deploy user:

   sudo visudo
   
   # Add these lines:
   deploy ALL=(ALL) NOPASSWD: /usr/bin/chown, /usr/bin/chmod, /usr/bin/systemctl reload nginx, /usr/bin/nginx, /usr/bin/mkdir, /usr/bin/cp, /usr/bin/rm
   

5. Configure nginx for multiple environments:

Production config (/etc/nginx/sites-available/mbpanel-docs-prod):

server {
    listen 80;
    server_name docs.yourdomain.com;
    root /var/www/mbpanel-docs/current;
    index index.html;

    # Include common configuration
    include /etc/nginx/conf.d/mbpanel-docs-common.conf;
}

Staging config (/etc/nginx/sites-available/mbpanel-docs-staging):

server {
    listen 80;
    server_name staging-docs.yourdomain.com;
    root /var/www/mbpanel-docs-staging/staging;
    index index.html;

    # Include common configuration
    include /etc/nginx/conf.d/mbpanel-docs-common.conf;
}

Preview config (/etc/nginx/sites-available/mbpanel-docs-preview):

server {
    listen 80;
    server_name preview-docs.yourdomain.com;
    root /var/www/mbpanel-docs-staging;
    index index.html;

    # Handle preview URLs
    location ~ ^/preview-pr-(\d+)/(.*)$ {
        alias /var/www/mbpanel-docs-staging/preview-pr-$1/$2;
        try_files $uri $uri/ $uri.html =404;
    }

    # Default to latest staging
    location / {
        alias /var/www/mbpanel-docs-staging/staging/;
        try_files $uri $uri/ $uri.html =404;
    }

    include /etc/nginx/conf.d/mbpanel-docs-common.conf;
}

Common config (/etc/nginx/conf.d/mbpanel-docs-common.conf):

# Copy from nginx-docs.conf (without server block)
gzip on;
gzip_vary on;
gzip_min_length 1024;
# ... rest of common configuration

1. Enable sites:

   sudo ln -s /etc/nginx/sites-available/mbpanel-docs-prod /etc/nginx/sites-enabled/
   sudo ln -s /etc/nginx/sites-available/mbpanel-docs-staging /etc/nginx/sites-enabled/
   sudo ln -s /etc/nginx/sites-available/mbpanel-docs-preview /etc/nginx/sites-enabled/
   sudo nginx -t
   sudo systemctl reload nginx
   

4. Test the Setup

Test SSH Connection:

ssh -i ~/.ssh/deploy-key deploy@your-server.com "whoami"

Test Manual Deployment:

# On your local machine
rsync -avz -e "ssh -i ~/.ssh/deploy-key" site/ deploy@your-server.com:/var/www/mbpanel-docs/current/

🔄 Workflow Triggers

Automatic Triggers:

• Push to main → Production deployment
• Push to develop → Staging deployment
• Pull Request → Preview deployment

Manual Triggers:

• Go to Actions → Deploy Documentation → Run workflow
• Choose environment: staging or production

📊 Workflow Features

Build Stage:

• ✅ Validates MkDocs configuration
• ✅ Builds documentation with strict mode
• ✅ Generates semantic search index (on main branch)
• ✅ Uploads build artifacts
• ✅ Generates build summary

Deployment Stages:

• ✅ Atomic deployments with backup
• ✅ Permission management
• ✅ Nginx configuration testing
• ✅ Health checks
• ✅ Rollback on failure

Preview Features:

• ✅ PR preview deployments
• ✅ Automatic preview links in PR comments
• ✅ Isolated preview environments

🛡️ Security Best Practices

SSH Key Security:

1. Use ed25519 keys (more secure than RSA)
2. Limit key permissions to deployment user only
3. Use GitHub secrets (never commit keys)
4. Rotate keys regularly

Server Security:

1. Minimal sudo permissions for deploy user
2. Separate environments (prod/staging/preview)
3. Regular backups before deployments
4. Nginx security headers configured

GitHub Security:

1. Environment protection rules
2. Required reviewers for production
3. Branch protection on main
4. Secret scanning enabled

🔧 Monitoring & Troubleshooting

View Workflow Status:

1. Go to Actions tab in GitHub
2. Click on Deploy Documentation workflow
3. View individual job logs

Common Issues:

SSH Connection Failed:

# Test SSH manually
ssh -i ~/.ssh/deploy-key deploy@your-server.com

# Check server logs
sudo journalctl -u sshd

Permission Denied:

# Check file permissions on server
ls -la /var/www/mbpanel-docs/

# Fix permissions
sudo chown -R deploy:deploy /var/www/mbpanel-docs/

Nginx Configuration Error:

# Test nginx config
sudo nginx -t

# Check nginx logs
sudo tail -f /var/log/nginx/error.log

Health Checks:

The workflow includes automatic health checks. You can also test manually:

# Production health
curl -I https://docs.yourdomain.com/health

# Staging health
curl -I http://staging-docs.yourdomain.com/health

📈 Advanced Features

Custom Domains:

Update nginx configs with your custom domains and SSL certificates.

CDN Integration:

Add Cloudflare or similar CDN in front of nginx for better performance.

Analytics:

Add Google Analytics or similar tracking to your MkDocs configuration.

Semantic Search:

Enable semantic search API by adding backend proxy to nginx configuration.

🚀 Going Live

Once everything is set up:

1. Push to develop to test staging deployment
2. Create PR to test preview deployment
3. Merge to main for production deployment

Your documentation will now automatically update on every push!