Vapora/docs/custom-deployment-setup.md

Custom Deployment Server Setup Guide

Complete reference for configuring mdBook documentation deployment to custom servers.

📋 What's Included

Deployment Script

File: .scripts/deploy-docs.sh (9.9 KB, executable)

Capabilities:

• ✅ 6 deployment methods (SSH, SFTP, HTTP, Docker, S3, GCS)
• ✅ Pre-flight validation (connectivity, files, permissions)
• ✅ Automatic backups (SSH/SFTP)
• ✅ Post-deployment verification
• ✅ Rollback support (SSH)
• ✅ Detailed logging and error handling

Configuration Files

Files: .scripts/.deploy-config.*

Templates for:

• ✅ .deploy-config.production — Production environment
• ✅ .deploy-config.staging — Staging/testing environment

Documentation

Files:

• ✅ docs/custom-deployment-server.md — Complete reference (45+ KB)
• ✅ .scripts/DEPLOYMENT_QUICK_START.md — Quick start guide (5 min setup)

---

🚀 Quick Start (5 Minutes)

Fastest Way: GitHub Pages

# 1. Repository → Settings → Pages
# 2. Select: GitHub Actions
# 3. Save
# 4. Push any docs/ change
# Done!

Fastest Way: SSH to Existing Server

# Generate SSH key
ssh-keygen -t ed25519 -f ~/.ssh/vapora-docs -N ""

# Add to server
ssh-copy-id -i ~/.ssh/vapora-docs user@your-server.com

# Add GitHub secrets (Settings → Secrets → Actions)
# DOCS_DEPLOY_METHOD = ssh
# DOCS_DEPLOY_HOST = your-server.com
# DOCS_DEPLOY_USER = user
# DOCS_DEPLOY_PATH = /var/www/docs
# DOCS_DEPLOY_KEY = [base64: cat ~/.ssh/vapora-docs | base64]

---

📦 Deployment Methods Comparison

Method	Setup	Speed	Cost	Best For
GitHub Pages	2 min	Fast	Free	Public docs
SSH	10 min	Medium	Server	Private docs, full control
S3 + CloudFront	5 min	Fast	$1-5/mo	Global scale
Docker	15 min	Medium	Varies	Container orchestration
HTTP API	20 min	Medium	Server	Custom deployment logic
GCS	5 min	Fast	$0.02/GB	Google Cloud users

---

🔐 Security

SSH Key Management

# Generate key securely
ssh-keygen -t ed25519 -f ~/.ssh/vapora-docs -N "strong-passphrase"

# Encode for GitHub (base64)
cat ~/.ssh/vapora-docs | base64 -w0 > /tmp/key.b64

# Add to GitHub Secrets (do NOT commit key anywhere)
# Settings → Secrets and variables → Actions → DOCS_DEPLOY_KEY

Principle of Least Privilege

# Create restricted deployment user
sudo useradd -m -d /var/www/docs -s /bin/false docs

# Grant only necessary permissions
sudo chmod 755 /var/www/docs
sudo chown docs:www-data /var/www/docs

# SSH key permissions (on server)
sudo -u docs chmod 700 ~/.ssh
sudo -u docs chmod 600 ~/.ssh/authorized_keys

Secrets Rotation

Recommended: Rotate deployment secrets quarterly

# Generate new key
ssh-keygen -t ed25519 -f ~/.ssh/vapora-docs-new -N ""

# Update on server
ssh-copy-id -i ~/.ssh/vapora-docs-new user@your-server.com

# Update GitHub secret
# Settings → Secrets → DOCS_DEPLOY_KEY → Update

# Remove old key from server
ssh user@your-server.com
sudo -u docs nano ~/.ssh/authorized_keys
# Delete old key, save

---

🎯 Deployment Flow

From Code to Live

Developer Push (docs/)
    ↓ GitHub Detects Change
    ↓
mdBook Build & Deploy Workflow
    ├─ Checkout repository
    ├─ Install mdBook
    ├─ Build documentation
    ├─ Validate output
    ├─ Upload artifact (30-day retention)
    └─ Done
    ↓
mdBook Publish & Sync Workflow (triggered)
    ├─ Download artifact
    ├─ Setup credentials
    ├─ Run deployment script
    │  ├─ Pre-flight checks
    │  │  ├─ Verify mdBook output exists
    │  │  ├─ Check server connectivity
    │  │  └─ Validate configuration
    │  ├─ Deploy (method-specific)
    │  │  ├─ SSH: rsync + backup
    │  │  ├─ S3: sync to bucket
    │  │  ├─ HTTP: upload archive
    │  │  ├─ Docker: push image
    │  │  └─ GCS: sync to bucket
    │  └─ Post-deployment verify
    ├─ Create deployment record
    ├─ Send notifications
    └─ Done
    ↓
✅ Documentation Live

Total Time: ~1-2 minutes

---

📊 File Structure

.github/
├── workflows/
│   ├── mdbook-build-deploy.yml       (Build workflow)
│   └── mdbook-publish.yml             (Deployment workflow) ✨ Updated
├── WORKFLOWS.md                       (Reference)
└── CI_CD_CHECKLIST.md                (Setup checklist)

.scripts/
├── deploy-docs.sh                     (Main script) ✨ New
├── .deploy-config.production          (Config) ✨ New
├── .deploy-config.staging             (Config) ✨ New
└── DEPLOYMENT_QUICK_START.md          (Quick guide) ✨ New

docs/
├── mdbook-setup.md                    (mdBook guide)
├── github-actions-setup.md            (Workflow details)
├── deployment-guide.md                (Deployment reference)
├── custom-deployment-server.md        (Complete setup) ✨ New
└── custom-deployment-setup.md         (This file) ✨ New

---

🔧 Environment Variables

Deployment Script Uses

# Core
DOCS_DEPLOY_METHOD              # ssh, sftp, http, docker, s3, gcs

# SSH/SFTP
DOCS_DEPLOY_HOST                # hostname or IP
DOCS_DEPLOY_USER                # remote username
DOCS_DEPLOY_PATH                # remote directory path
DOCS_DEPLOY_KEY                 # SSH private key (base64)

# HTTP
DOCS_DEPLOY_ENDPOINT            # HTTP endpoint URL
DOCS_DEPLOY_TOKEN               # Bearer token

# AWS S3
AWS_ACCESS_KEY_ID               # AWS credentials
AWS_SECRET_ACCESS_KEY
AWS_DOCS_BUCKET                 # S3 bucket name
AWS_REGION                      # AWS region

# Google Cloud Storage
GOOGLE_APPLICATION_CREDENTIALS  # Service account JSON
GCS_DOCS_BUCKET                 # GCS bucket name

# Docker
DOCKER_REGISTRY                 # Registry hostname
DOCKER_USERNAME                 # Docker credentials
DOCKER_PASSWORD

---

✅ Setup Checklist

Pre-Setup

• Choose deployment method
• Prepare server/cloud account
• Generate credentials
• Read relevant documentation

SSH/SFTP Setup

• Create docs user on server
• Configure SSH directory and permissions
• Add SSH public key to server
• Test SSH connectivity
• Install nginx/apache on server
• Configure web server for docs

GitHub Configuration

• Add GitHub secret: DOCS_DEPLOY_METHOD
• Add deployment credentials (method-specific)
• Verify secrets are not visible
• Review updated workflows
• Enable Actions tab

Testing

• Build documentation locally
• Run deployment script locally (if possible)
• Make test commit to docs/
• Monitor Actions tab
• Verify workflow completed
• Check documentation site
• Test search functionality
• Test dark mode

Monitoring

• Set up log monitoring
• Configure webhook notifications
• Create deployment dashboard
• Set up alerts for failures

Maintenance

• Document your setup
• Schedule credential rotation
• Test rollback procedure
• Plan backup strategy

---

🆘 Common Issues

Issue: "Cannot connect to server"

Cause: SSH connectivity problem

Fix:

# Test SSH directly
ssh -vvv -i ~/.ssh/vapora-docs user@your-server.com

# Check GitHub secret encoding
cat ~/.ssh/vapora-docs | base64 | wc -c
# Should be long string

# Verify server firewall
ssh -p 22 user@your-server.com echo "ok"

Issue: "rsync: command not found"

Cause: rsync not installed on server

Fix:

ssh user@your-server.com
sudo apt-get install rsync  # Debian/Ubuntu
# OR
sudo yum install rsync      # RedHat/CentOS

Issue: "Permission denied" on server

Cause: docs user doesn't have write permission

Fix:

ssh user@your-server.com
sudo chown -R docs:docs /var/www/docs
sudo chmod -R 755 /var/www/docs

Issue: Documentation not appearing on site

Cause: nginx not configured or files not updated

Fix:

# Check nginx config
sudo nginx -T | grep root

# Verify files are there
sudo ls -la /var/www/docs/index.html

# Reload nginx
sudo systemctl reload nginx

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

Issue: GitHub Actions fails with "No secrets found"

Cause: Secrets not configured

Fix:

# Settings → Secrets and variables → Actions
# Verify all required secrets are present
# Check spelling matches deployment script

---

📈 Performance Monitoring

Workflow Performance

Track metrics after each deployment:

Build Time:     ~2-3 seconds
Deploy Time:    ~10-30 seconds (method-dependent)
Total Time:     ~1-2 minutes

Site Performance

Monitor after deployment:

# Page load time
curl -w "Time: %{time_total}s\n" https://docs.your-domain.com/

# Lighthouse audit
lighthouse https://docs.your-domain.com

# Cache headers
curl -I https://docs.your-domain.com/ | grep Cache-Control

Artifact Management

Default: 30 days retention

# View artifacts
GitHub → Actions → Workflow run → Artifacts

# Manual cleanup
# (GitHub handles auto-cleanup after 30 days)

---

🔄 Disaster Recovery

Rollback Procedure (SSH)

# SSH into server
ssh -i ~/.ssh/vapora-docs user@your-server.com

# List backups
ls -la /var/www/docs/backups/

# Restore from backup
sudo -u docs mv /var/www/docs/current /var/www/docs/current-failed
sudo -u docs mv /var/www/docs/backups/backup_20260112_143000 \
                /var/www/docs/current
sudo -u docs ln -sfT /var/www/docs/current /var/www/docs/docs

Manual Deployment (No GitHub Actions)

# Build locally
cd docs
mdbook build

# Deploy using script
DOCS_DEPLOY_METHOD=ssh \
DOCS_DEPLOY_HOST=your-server.com \
DOCS_DEPLOY_USER=docs \
DOCS_DEPLOY_PATH=/var/www/docs \
bash .scripts/deploy-docs.sh production

---

📞 Support Resources

Topic	Location
Quick Start	.scripts/DEPLOYMENT_QUICK_START.md
Full Reference	docs/custom-deployment-server.md
Workflow Details	.github/WORKFLOWS.md
Setup Checklist	.github/CI_CD_CHECKLIST.md
Deployment Script	.scripts/deploy-docs.sh
mdBook Guide	docs/mdbook-setup.md

---

✨ What's New

✨ = New with custom deployment setup

New Files:

• ✨ .scripts/deploy-docs.sh (9.9 KB)
• ✨ .scripts/.deploy-config.production
• ✨ .scripts/.deploy-config.staging
• ✨ .scripts/DEPLOYMENT_QUICK_START.md
• ✨ docs/custom-deployment-server.md (45+ KB)
• ✨ docs/custom-deployment-setup.md (This file)

Updated Files:

• ✨ .github/workflows/mdbook-publish.yml (Enhanced with deployment integration)

Total Addition: ~100 KB documentation + deployment scripts

---

🎓 Learning Path

Beginner (Just want it working):

1. Read: .scripts/DEPLOYMENT_QUICK_START.md (5 min)
2. Choose: SSH or GitHub Pages
3. Setup: Follow instructions (10 min)
4. Test: Push docs/ change (automatic)

Intermediate (Want to understand):

1. Read: docs/github-actions-setup.md (15 min)
2. Read: .github/WORKFLOWS.md (10 min)
3. Setup: Full SSH deployment (20 min)

Advanced (Want all options):

1. Read: docs/custom-deployment-server.md (30 min)
2. Study: .scripts/deploy-docs.sh (15 min)
3. Setup: Multiple deployment targets (60 min)

---

📞 Need Help?

Quick Questions:

• Check: .scripts/DEPLOYMENT_QUICK_START.md
• Check: .github/WORKFLOWS.md

Detailed Setup:

• Reference: docs/custom-deployment-server.md
• Reference: docs/deployment-guide.md

Troubleshooting:

• Check: docs/custom-deployment-server.md → "Troubleshooting"
• Check: .github/CI_CD_CHECKLIST.md → "Troubleshooting Reference"

---

Last Updated: 2026-01-12 Status: ✅ Production Ready Total Setup Time: 5-20 minutes (depending on method)

For immediate next steps, see: .scripts/DEPLOYMENT_QUICK_START.md