Vapora/.scripts/deployment_quick_start.md

# Deployment Quick Start Guide

Get your mdBook documentation deployed in minutes.

## Choose Your Deployment Method

### 🔄 Option 1: SSH/SFTP (Recommended for Most)

**Best for**: Private servers, simple setup, full control

**Setup Time**: 10 minutes

```bash
# 1. Create SSH key pair (if needed)
ssh-keygen -t ed25519 -f ~/.ssh/vapora-docs -N ""

# 2. SSH into your server and set up docs user
ssh user@your-server.com
sudo useradd -m -d /var/www/docs -s /bin/bash docs
sudo mkdir -p /var/www/docs/.ssh
sudo chmod 700 /var/www/docs/.ssh
exit

# 3. Add public key to server
cat ~/.ssh/vapora-docs.pub | ssh user@your-server.com \
  "sudo -u docs tee -a /var/www/docs/.ssh/authorized_keys"

# 4. Test connection
ssh -i ~/.ssh/vapora-docs docs@your-server.com ls

# 5. Add GitHub secrets
# Settings → Secrets and variables → Actions → New repository secret
# DOCS_DEPLOY_METHOD = ssh
# DOCS_DEPLOY_HOST = your-server.com
# DOCS_DEPLOY_USER = docs
# DOCS_DEPLOY_PATH = /var/www/docs
# DOCS_DEPLOY_KEY = [base64 encode: cat ~/.ssh/vapora-docs | base64]
```

### ☁️ Option 2: AWS S3 (Best for Scale)

**Best for**: High availability, CDN, minimal ops

**Setup Time**: 5 minutes

```bash
# 1. Create IAM user
aws iam create-user --user-name vapora-docs-deployer
aws iam create-access-key --user-name vapora-docs-deployer

# 2. Create S3 bucket
aws s3 mb s3://vapora-docs --region us-east-1

# 3. Attach policy (copy from docs/CUSTOM_DEPLOYMENT_SERVER.md)

# 4. Add GitHub secrets
# DOCS_DEPLOY_METHOD = s3
# AWS_ACCESS_KEY_ID = [from step 1]
# AWS_SECRET_ACCESS_KEY = [from step 1]
# AWS_DOCS_BUCKET = vapora-docs
# AWS_REGION = us-east-1
```

### 🌐 Option 3: GitHub Pages (Simplest)

**Best for**: Public documentation, zero server ops

**Setup Time**: 2 minutes

```bash
# 1. Go to Settings → Pages
# 2. Select Source: GitHub Actions
# 3. Save
# 4. Push any docs/ change
# Done! Automatic deployment in 1-2 minutes
```

---

## Minimal SSH Setup (Step-by-Step)

### On Your Server

```bash
# 1. Create docs directory
mkdir -p /var/www/docs
cd /var/www/docs

# 2. Set up for web serving
sudo apt-get install nginx -y  # or yum install nginx

# 3. Create nginx config
sudo tee /etc/nginx/sites-available/docs > /dev/null << 'EOF'
server {
    listen 80;
    server_name docs.your-domain.com;
    root /var/www/docs;

    location / {
        index index.html;
        try_files $uri $uri/ =404;
    }

    location ~* \.(js|css|fonts)$ {
        expires 1h;
    }
}
EOF

# 4. Enable site
sudo ln -s /etc/nginx/sites-available/docs /etc/nginx/sites-enabled/
sudo nginx -t && sudo systemctl reload nginx
```

### On Your Local Machine

```bash
# 1. Create SSH key (if needed)
ssh-keygen -t ed25519 -f ~/.ssh/vapora-docs -N ""

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

# 3. Test
ssh -i ~/.ssh/vapora-docs user@your-server.com

# 4. Base64 encode key for GitHub
cat ~/.ssh/vapora-docs | base64 -w0 > /tmp/key.b64
cat /tmp/key.b64  # Copy this
```

### In GitHub

Go to **Settings** → **Secrets and variables** → **Actions**

Create these secrets:

| Name | Value |
|------|-------|
| `DOCS_DEPLOY_METHOD` | `ssh` |
| `DOCS_DEPLOY_HOST` | `your-server.com` |
| `DOCS_DEPLOY_USER` | `user` |
| `DOCS_DEPLOY_PATH` | `/var/www/docs` |
| `DOCS_DEPLOY_KEY` | Paste base64-encoded key |

---

## Test Your Setup

### Local Test

```bash
# Build locally
cd docs
mdbook build

# Test deployment script
bash ../.scripts/deploy-docs.sh production
```

### GitHub Actions Test

```bash
# Make a test commit
git add docs/README.md
git commit -m "test: trigger deployment"
git push origin main

# Watch Actions tab
# Actions → mdBook Publish & Sync → View run
```

---

## Verify Deployment

### Check SSH Deployment

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

# Verify files
ls -lah /var/www/docs/
cat /var/www/docs/index.html | head -20

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

### Check S3 Deployment

```bash
aws s3 ls s3://vapora-docs/

# Or visit via CloudFront
https://docs-cdn.cloudfront.net/
```

### Check GitHub Pages

```bash
# Visit the URL shown in Settings → Pages
https://username.github.io/vapora/
```

---

## Common Issues & Fixes

### SSH Connection Fails

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

# Check key permissions
ls -la ~/.ssh/vapora-docs
chmod 600 ~/.ssh/vapora-docs
chmod 700 ~/.ssh

# Add server to known_hosts
ssh-keyscan your-server.com >> ~/.ssh/known_hosts
```

### Deployment Script Can't Find Files

```bash
# Verify mdBook built successfully
cd docs
mdbook build
ls -la book/index.html
```

### Files Not Appearing on Website

```bash
# Check nginx root directory
sudo nginx -T | grep root

# Verify permissions
sudo ls -la /var/www/docs/

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

### GitHub Actions Fails

1. Go to **Actions** → Failed workflow
2. Expand **Deploy to Custom Server** step
3. Look for error message
4. Common issues:
   - Secret not set correctly
   - SSH key not base64 encoded
   - Server not reachable

---

## Next Steps

1. Choose deployment method above
2. Follow setup instructions
3. Test locally: `bash .scripts/deploy-docs.sh production`
4. Push test commit to trigger GitHub Actions
5. Monitor Actions tab
6. Verify deployment succeeded
7. Check your documentation site

---

## Need Help?

- Full guide: See `docs/CUSTOM_DEPLOYMENT_SERVER.md`
- Workflow reference: See `.github/WORKFLOWS.md`
- Deployment script: `.scripts/deploy-docs.sh`
- GitHub Secrets: Repository → Settings → Secrets and variables → Actions

---

**Last Updated**: 2026-01-12
**Estimated Setup Time**: 10-15 minutes