hatch-surf/DEPLOYMENT.md

Hatch Landing Page — Deployment Guide

Overview

The Hatch landing page (hatch.surf) is a static HTML site deployed via Docker on the production server.

Key principle: All changes MUST go through the git repository and automated deployment. Never edit files directly on the server or use /var/www.

---

Repository

Location: /home/nara/apps/web/

Git Remotes:

• github → elfoundation/hatch (source of truth)
• origin → el-foundation/hatch-surf (Gitea push-mirror, deploys to hatch.surf)

Structure:

site/                   # Static files served by nginx
  index.html            # Main landing page
  style.css             # Styles
  main.js               # Anime.js animations
Dockerfile              # Docker build configuration (static files only)
docker-compose.yml      # Container orchestration
deploy.sh               # Deployment script

---

Deployment Flow

Source of Truth

GitHub main is the source of truth. Gitea is a push-mirror.

All development happens via PRs to elfoundation/hatch. The deploy script pulls from GitHub and pushes to Gitea.

Automatic (Recommended)

1. Merge PR to GitHub main
2. Gitea webhook triggers gitea-webhook.py
3. Script runs deploy.sh automatically
4. deploy.sh pulls from GitHub, pushes to Gitea (push-mirror), rebuilds Docker, restarts

Manual

cd /home/nara/apps/web
./deploy.sh

What deploy.sh does:

1. git pull github main — fetches latest from GitHub (source of truth)
2. git push origin main — syncs to Gitea (push-mirror)
3. cd site && docker build -t hatch-web:latest . — rebuilds image
4. Stops and removes old container
5. docker run -d — starts new container
6. Verifies deployment with health check

---

Docker Setup

Container: hatch-web
Port: 8080 (mapped to host)
Internal: nginx serving static files on port 80
Network: hatch-network

Check status:

docker ps | grep hatch-web
docker logs hatch-web

Restart without rebuild:

docker compose -f /home/nara/apps/web/docker-compose.yml restart

---

Making Changes

1. Edit the static files

cd /home/nara/apps/web

# Edit landing page
vim out/index.html

# Edit styles
vim out/style.css

# Edit animations
vim out/main.js

2. Test locally (optional)

# Serve files locally
cd out && python3 -m http.server 3000
# Visit http://localhost:3000

3. Commit and push

git add .
git commit -m "Description of changes"
git push origin main

4. Deploy

Either wait for webhook or run manually:

./deploy.sh

5. Verify

curl -s http://localhost:8080 | head -20
# Or visit https://hatch.surf

---

Common Mistakes to Avoid

❌ DON'T: Edit files in /var/www/html/
❌ DON'T: Edit files directly inside the Docker container
❌ DON'T: Work on static HTML/CSS files in a workspace without committing
❌ DON'T: Copy files to the server without using git

✅ DO: Edit files in /home/nara/apps/web/out/
✅ DO: Commit changes to git
✅ DO: Use deploy.sh for deployment
✅ DO: Test locally before pushing

---

Rollback

If a deployment causes issues:

cd /home/nara/apps/web

# View recent commits
git log --oneline -10

# Revert to previous version
git revert HEAD
git push origin main

# Redeploy
./deploy.sh

Previous builds are backed up in out.backup.* directories.

---

Cache Headers

HTML pages: no-cache, must-revalidate — browsers always revalidate, ensuring fresh content after deploys.

Static assets (CSS/JS/images): public, immutable with 1-year expiry.

Nginx config: Built into the Dockerfile.

If users report seeing old content after deployment:

1. Verify the container is running: docker ps | grep hatch-web
2. Check the HTML has new content: curl -s http://localhost:8080 | head -5
3. Ask user to hard refresh: Ctrl+Shift+R (Chrome/Firefox) or Cmd+Shift+R (Mac)

---

Troubleshooting

Container not starting:

docker logs hatch-web
docker compose -f /home/nara/apps/web/docker-compose.yml up -d

Changes not showing:

1. Verify commit pushed: git log --oneline -1
2. Check container was rebuilt: docker images | grep hatch-web
3. Force rebuild: cd /home/nara/apps/web && docker build -t hatch-web:latest . && docker compose up -d

Port conflict:

lsof -i :8080
# Kill conflicting process or change port in docker-compose.yml

---

Contact

• DevOps: Jing Yang (Sam Lee)
• CTO: Jordan Patel
• Repository: /home/nara/apps/web/
• Live site: https://hatch.surf