Vapora/docs/DEPLOYMENT_GUIDE.md

mdBook Deployment Guide

Complete guide for deploying VAPORA documentation to production.

📋 Pre-Deployment Checklist

Before deploying documentation:

• Local build succeeds: mdbook build
• No broken links in src/SUMMARY.md
• All markdown follows formatting standards
• book.toml is valid TOML
• Each subdirectory has README.md
• All relative paths are correct
• Git workflows are configured

---

🚀 Deployment Options

Option 1: GitHub Pages (GitHub.com)

Best for: Public documentation, free hosting

Setup:

1. Go to repository Settings → Pages
2. Under Build and deployment:
   • Source: GitHub Actions
   • (Leave branch selection empty)
3. Save settings

Deployment Process:

# Make documentation changes
git add docs/
git commit -m "docs: update content"
git push origin main

# Automatic workflow triggers:
# 1. mdBook Build & Deploy starts
# 2. Builds documentation
# 3. Uploads to GitHub Pages
# 4. Available at: https://username.github.io/repo-name/

Verify Deployment:

1. Go to Settings → Pages
2. Look for Your site is live at: https://...
3. Click link to verify
4. Hard refresh if needed (Ctrl+Shift+R)

Custom Domain (optional):

1. Settings → Pages → Custom domain
2. Enter domain: docs.vapora.io
3. Add DNS record (CNAME):

   docs.vapora.io CNAME username.github.io
   

4. Wait 5-10 minutes for DNS propagation

---

Option 2: Custom Server / Self-Hosted

Best for: Private documentation, custom deployment

Setup:

1. Create deployment script (e.g., deploy.sh):

#!/bin/bash
# .scripts/deploy-docs.sh

cd docs
mdbook build

# Copy to web server
scp -r book/ user@server:/var/www/docs/

echo "Documentation deployed!"

2. Add to workflow .github/workflows/mdbook-publish.yml:

- name: Deploy to custom server
  run: bash .scripts/deploy-docs.sh
  env:
    DEPLOY_HOST: ${{ secrets.DEPLOY_HOST }}
    DEPLOY_USER: ${{ secrets.DEPLOY_USER }}
    DEPLOY_KEY: ${{ secrets.DEPLOY_KEY }}

3. Add secrets in Settings → Secrets and variables → Actions

---

Option 3: Docker & Container Registry

Best for: Containerized deployment

Dockerfile:

FROM nginx:alpine

# Install mdBook
RUN apk add --no-cache curl && \
    curl -L https://github.com/rust-lang/mdBook/releases/download/v0.4.36/mdbook-v0.4.36-x86_64-unknown-linux-gnu.tar.gz | tar xz -C /usr/local/bin

# Copy docs
COPY docs /docs

# Build
WORKDIR /docs
RUN mdbook build

# Serve with nginx
FROM nginx:alpine
COPY --from=0 /docs/book /usr/share/nginx/html

EXPOSE 80
CMD ["nginx", "-g", "daemon off;"]

Build & Push:

docker build -t myrepo/vapora-docs:latest .
docker push myrepo/vapora-docs:latest

---

Option 4: CDN & Cloud Storage

Best for: High availability, global distribution

AWS S3 + CloudFront

- name: Deploy to S3
  run: |
    aws s3 sync docs/book s3://my-docs-bucket/docs \
      --delete --region us-east-1
  env:
    AWS_ACCESS_KEY_ID: ${{ secrets.AWS_ACCESS_KEY_ID }}
    AWS_SECRET_ACCESS_KEY: ${{ secrets.AWS_SECRET_ACCESS_KEY }}

Google Cloud Storage

- name: Deploy to GCS
  run: |
    gsutil -m rsync -d -r docs/book gs://my-docs-bucket/docs
  env:
    GCLOUD_SERVICE_KEY: ${{ secrets.GCLOUD_SERVICE_KEY }}

---

🔄 Automated Deployment Workflow

Push to Main

Your Changes
    ↓
git push origin main
    ↓
GitHub Triggers Workflows
    ↓
mdBook Build & Deploy Starts
    ├─ Checkout code
    ├─ Install mdBook
    ├─ Build documentation
    ├─ Validate quality
    ├─ Upload artifact
    └─ Deploy to Pages (or custom)
    ↓
Documentation Live

Manual Artifact Deployment

For non-automated deployments:

1. Trigger workflow manually (if configured):

   Actions → mdBook Build & Deploy → Run workflow
   

2. Wait for completion

3. Download artifact:

   Click run → Artifacts → mdbook-site-{sha}
   

4. Extract and deploy:

   unzip mdbook-site-abc123.zip
   scp -r book/* user@server:/var/www/docs/
   

---

🔐 Security Considerations

Secrets Management

Never commit API keys or credentials. Use GitHub Secrets:

# Add secret
Settings → Secrets and variables → Actions → New repository secret

Name: DEPLOY_TOKEN
Value: your-token-here

Reference in workflow:

env:
  DEPLOY_TOKEN: ${{ secrets.DEPLOY_TOKEN }}

Branch Protection

Prevent direct pushes to main:

Settings → Branches → Add rule
├─ Branch name pattern: main
├─ Require pull request reviews: 1
├─ Dismiss stale PR approvals: ✓
├─ Require status checks to pass: ✓
└─ Include administrators: ✓

Access Control

Limit who can deploy:

1. Settings → Environments → Create new
2. Name: docs or production
3. Under "Required reviewers": Add team/users
4. Deployments require approval

---

📊 Monitoring Deployment

GitHub Actions Dashboard

View all deployments:

Actions → All workflows → mdBook Build & Deploy

Check individual run:

• Status (✅ Success, ❌ Failed)
• Execution time
• Log details
• Artifact details

Health Checks

Monitor deployed documentation:

# Check if site is live
curl -I https://docs.vapora.io

# Expected: 200 OK
# Check content
curl https://docs.vapora.io | grep "VAPORA"

Performance Monitoring

1. Lighthouse (local):

   lighthouse https://docs.vapora.io
   

2. GitHub Pages Analytics (if enabled)

3. Custom monitoring:

   • Check response time
   • Monitor 404 errors
   • Track page views

---

🔍 Troubleshooting Deployment

Issue: GitHub Pages shows 404

Cause: Pages not configured or build failed

Fix:

1. Settings → Pages → Verify source is "GitHub Actions"
2. Check Actions tab for build failures
3. Hard refresh browser (Ctrl+Shift+R)
4. Wait 1-2 minutes if just deployed

Issue: Custom domain not resolving

Cause: DNS not propagated or CNAME incorrect

Fix:

# Check DNS resolution
nslookup docs.vapora.io

# Should show correct IP
# Wait 5-10 minutes if just created
# Check CNAME record:
dig docs.vapora.io CNAME

Issue: Old documentation still showing

Cause: Browser cache or CDN cache

Fix:

# Hard refresh in browser
Ctrl+Shift+R (Windows/Linux)
Cmd+Shift+R (Mac)

# Or clear entire browser cache
# Settings → Privacy → Clear browsing data

# For CDN: Purge cache
AWS CloudFront: Go to Distribution → Invalidate

Issue: Deployment workflow fails

Check logs:

1. Go to Actions → Failed run
2. Click job name
3. Expand failed step
4. Look for error message

Common errors:

Error	Fix
mdbook: command not found	First run takes time to install
Cannot find file	Check SUMMARY.md relative paths
Permission denied	Check deployment secrets/keys
Network error	Check firewall/connectivity

---

📝 Post-Deployment Tasks

After successful deployment:

Verification

• Site loads at correct URL
• Search functionality works
• Dark mode toggles
• Print works (Ctrl+P)
• Mobile layout responsive
• Links work
• Code blocks highlight properly

Notification

• Announce new docs in release notes
• Update README with docs link
• Share link in team/community channels
• Update analytics tracking (if applicable)

Monitoring

• Set up 404 alerts
• Monitor page load times
• Track deployment frequency
• Review error logs regularly

---

🔄 Update Process

For Regular Updates

Documentation updates:

# 1. Update content
vi docs/setup/setup-guide.md

# 2. Test locally
cd docs && mdbook serve

# 3. Commit and push
git add docs/
git commit -m "docs: update setup guide"
git push origin main

# 4. Automatic deployment (3-5 minutes)

For Major Releases

# 1. Update version numbers
vi docs/book.toml  # Update title/description

# 2. Add changelog entry
vi docs/README.md

# 3. Build and verify
cd docs && mdbook clean && mdbook build

# 4. Create release commit
git add docs/
git commit -m "chore: release docs v1.2.0"
git tag -a v1.2.0 -m "Documentation v1.2.0"

# 5. Push
git push origin main --tags

# 6. Automatic deployment

---

🎯 Best Practices

Documentation Maintenance

• ✅ Update docs with every code change
• ✅ Keep SUMMARY.md in sync with content
• ✅ Use relative links consistently
• ✅ Test links before deploying
• ✅ Review markdown formatting

Deployment Best Practices

• ✅ Always test locally first
• ✅ Review workflow logs after deployment
• ✅ Monitor for 404 errors
• ✅ Keep 30-day artifact backups
• ✅ Document deployment procedures
• ✅ Set up redundant deployments
• ✅ Have rollback plan ready

Security Best Practices

• ✅ Use GitHub Secrets for credentials
• ✅ Enable branch protection on main
• ✅ Require status checks before merge
• ✅ Limit deployment access
• ✅ Audit deployment logs
• ✅ Rotate credentials regularly

---

📞 Support & Resources

Documentation

• .github/WORKFLOWS.md — Workflow quick reference
• docs/MDBOOK_SETUP.md — mdBook setup guide
• docs/GITHUB_ACTIONS_SETUP.md — Full workflow documentation
• docs/README.md — Documentation standards

External Resources

• mdBook Documentation
• GitHub Actions Docs
• GitHub Pages

Troubleshooting

• Check workflow logs: Repository → Actions → Failed run
• Enable verbose logging: Add --verbose flags
• Test locally: cd docs && mdbook serve

---

Last Updated: 2026-01-12 Status: ✅ Ready for Production

For workflow configuration details, see: .github/workflows/mdbook-*.yml