hatch-surf/docs/engineering/deploy-homepage.md

Deploying the Hatch Homepage

This document describes how the Hatch static homepage is deployed to hatch.surf.

Overview

The homepage is deployed to two locations:

1. GitHub Pages - Serves as a fallback and for GitHub-based discovery
2. hatch.surf server - Primary deployment at https://hatch.surf

Architecture

site/
├── index.html          # Main homepage
├── style.css           # Stylesheet
├── brand/              # Logo and favicon assets
│   ├── favicon/
│   └── og/
└── blog/               # Blog directory (placeholder)

Server Setup

Prerequisites

• Server: 46.250.250.48 (hatch.surf)
• nginx installed and configured
• Let's Encrypt certificate for hatch.surf
• SSH access for deployment

Nginx Configuration

The nginx server block is located at:

• /etc/nginx/sites-available/hatch.surf.conf
• Symlinked to /etc/nginx/sites-enabled/hatch.surf.conf

Configuration highlights:

• HTTP → HTTPS redirect
• SSL with Let's Encrypt certificate
• Security headers (X-Content-Type-Options, X-Frame-Options, Referrer-Policy)
• Gzip compression
• Static asset caching (30 days)

SSL Certificate

• Certificate managed by Let's Encrypt
• Auto-renewal via certbot
• Expiry: September 22, 2026

Deployment

Automated (GitHub Actions)

When changes are pushed to main branch affecting site/ directory:

1. GitHub Pages - Deployed automatically via GitHub Actions
2. Server - Deployed via rsync to /var/www/hatch.surf/

Required GitHub secrets:

• DEPLOY_HOST - Server IP (46.250.250.48)
• DEPLOY_USER - SSH username (root)
• DEPLOY_KEY - SSH private key (base64 encoded)

Manual Deployment

Use the deployment script:

# Dry run
./scripts/deploy-site.sh --dry-run

# Deploy
DEPLOY_HOST=46.250.250.48 \
DEPLOY_USER=root \
DEPLOY_KEY=$(cat ~/.ssh/id_rsa | base64) \
./scripts/deploy-site.sh

Direct rsync

rsync -avz --delete site/ root@46.250.250.48:/var/www/hatch.surf/
ssh root@46.250.250.48 "nginx -t && systemctl reload nginx"

Direct Deployment (When Running on Server)

If you're running on the same server as hatch.surf (e.g., in a Paperclip agent environment), you can deploy directly without SSH:

# Copy files directly to the deployment directory
sudo cp site/index.html /var/www/hatch.surf/index.html
sudo cp site/style.css /var/www/hatch.surf/style.css
sudo cp site/main.js /var/www/hatch.surf/main.js

# Set correct ownership
sudo chown www-data:www-data /var/www/hatch.surf/index.html
sudo chown www-data:www-data /var/www/hatch.surf/style.css
sudo chown www-data:www-data /var/www/hatch.surf/main.js

# Verify deployment
curl -s -I https://hatch.surf

Note: This method was used successfully in ELF-196 when the agent had direct server access.

Verification

Check Site Status

# HTTP redirect
curl -s -o /dev/null -w "%{http_code}" http://hatch.surf/

# HTTPS site
curl -s -o /dev/null -w "%{http_code}" https://hatch.surf/

# SSL certificate
curl -v https://hatch.surf/ 2>&1 | grep -E "expire|issuer|subject"

# Static assets
curl -s -o /dev/null -w "%{http_code}" https://hatch.surf/style.css
curl -s -o /dev/null -w "%{http_code}" https://hatch.surf/brand/og/default.png

Browser Verification

1. Visit https://hatch.surf
2. Verify no browser warnings (SSL valid)
3. Check that all assets load (CSS, images)
4. Test responsive design

Troubleshooting

SSL Certificate Issues

# Check certificate status
sudo certbot certificates

# Renew certificate manually
sudo certbot renew --cert-name hatch.surf

# Test nginx config
sudo nginx -t

Deployment Failures

1. Check GitHub Actions logs
2. Verify SSH access: ssh root@46.250.250.48
3. Check nginx status: sudo systemctl status nginx
4. Check nginx logs: sudo tail -f /var/log/nginx/error.log

Missing Assets

1. Verify files exist on server: ls -la /var/www/hatch.surf/brand/
2. Check nginx access logs: sudo tail -f /var/log/nginx/access.log
3. Ensure proper file permissions: chown -R www-data:www-data /var/www/hatch.surf

Maintenance

Updating Content

1. Edit files in site/ directory
2. Commit and push to main branch
3. GitHub Actions will auto-deploy to both locations

SSL Renewal

Certbot is configured to auto-renew. To check renewal status:

sudo certbot renew --dry-run

Backup

The site is version-controlled in Git. For server backups:

# Backup nginx config
sudo tar -czf nginx-hatch-backup.tar.gz /etc/nginx/sites-available/hatch.surf.conf /etc/letsencrypt/live/hatch.surf/

Related Issues

• ELF-192 - Build homepage and deploy it on hatch.surf
• ELF-171 - Server setup (nginx, SSL)
• ELF-196 - Deploy redesigned hatch.surf homepage (v2 files from ELF-195)