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

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

### Fastest Way: SSH to Existing Server

```bash
# 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

```bash
# 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

```bash
# 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

```bash
# 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

```bash
# 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**:
```bash
# 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**:
```bash
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**:
```bash
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**:
```bash
# 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**:
```bash
# 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:

```bash
# 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

```bash
# View artifacts
GitHub → Actions → Workflow run → Artifacts

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

---

## 🔄 Disaster Recovery

### Rollback Procedure (SSH)

```bash
# 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)

```bash
# 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`