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**:

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

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

```yaml
- 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**:

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

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

```yaml
- 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

```yaml
- 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:
   ```bash
   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:

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

Name: DEPLOY_TOKEN
Value: your-token-here
```

Reference in workflow:
```yaml
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:

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

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

```bash
# 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](https://rust-lang.github.io/mdBook/)
- [GitHub Actions Docs](https://docs.github.com/en/actions)
- [GitHub Pages](https://pages.github.com/)

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