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

# 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

# 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

# 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

# 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

# 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

# Build locally
cd docs
mdbook build

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

GitHub Actions Test

# 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

# 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

aws s3 ls s3://vapora-docs/

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

Check GitHub Pages

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

---

Common Issues & Fixes

SSH Connection Fails

# 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

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

Files Not Appearing on Website

# 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