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/

Structure:

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

---

Deployment Flow

Automatic (Recommended)

1. Push changes to main branch
2. Gitea webhook triggers gitea-webhook.py
3. Script runs deploy.sh automatically
4. Docker image rebuilds and container restarts

Manual

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

What deploy.sh does:

1. git pull origin main — fetches latest changes
2. docker build -t hatch-web:latest . — rebuilds image
3. Stops and removes old container
4. docker compose up -d — starts new container
5. 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