el-foundation/hatch-surf
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: update DEPLOYMENT.md for static landing page architecture

Browse Source 
Co-Authored-By: Paperclip <noreply@paperclip.ing>
This commit is contained in:
Riley Zhang 2026-06-25 03:36:37 +02:00
parent 0dbbf0b9bf
commit 6445fb6e12
1 changed files with 27 additions and 28 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

51
DEPLOYMENT.md
View File

@ -2,7 +2,7 @@
## Overview ## Overview
The Hatch landing page (`hatch.surf`) is a **Next.js** app deployed via **Docker** on the production server. 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`. **Key principle**: All changes MUST go through the git repository and automated deployment. Never edit files directly on the server or use `/var/www`.
@ -14,12 +14,12 @@ The Hatch landing page (`hatch.surf`) is a **Next.js** app deployed via **Docker
**Structure**: **Structure**:
``` ```
/app/page.tsx # Main page component out/ # Static files served by nginx
/app/layout.tsx # Root layout index.html # Main landing page
/app/globals.css # Global styles style.css # Styles
/components/ # React components (Hero, Features, Why, CTA, Footer, Header) main.js # Anime.js animations
/public/ # Static assets brand/favicon/ # Favicon assets
Dockerfile # Docker build configuration Dockerfile # Docker build configuration (static files only)
docker-compose.yml # Container orchestration docker-compose.yml # Container orchestration
deploy.sh # Deployment script deploy.sh # Deployment script
``` ```
@ -55,7 +55,7 @@ cd /home/nara/apps/web
**Container**: `hatch-web` **Container**: `hatch-web`
**Port**: `8080` (mapped to host) **Port**: `8080` (mapped to host)
**Internal**: nginx serving static Next.js export on port 80 **Internal**: nginx serving static files on port 80
**Network**: `hatch-network` **Network**: `hatch-network`
**Check status**: **Check status**:
@ -73,24 +73,26 @@ docker compose -f /home/nara/apps/web/docker-compose.yml restart
## Making Changes ## Making Changes
### 1. Edit the source code ### 1. Edit the static files
```bash ```bash
cd /home/nara/apps/web cd /home/nara/apps/web
# Edit components # Edit landing page
vim components/Hero.tsx vim out/index.html
vim components/Features.tsx
# etc.
# Edit styles # Edit styles
vim app/globals.css vim out/style.css
# Edit animations
vim out/main.js
``` ```
### 2. Test locally (optional) ### 2. Test locally (optional)
```bash ```bash
npm run dev # Serve files locally
cd out && python3 -m http.server 3000
# Visit http://localhost:3000 # Visit http://localhost:3000
``` ```
@ -122,13 +124,13 @@ curl -s http://localhost:8080 | head -20
❌ **DON'T**: Edit files in `/var/www/html/` ❌ **DON'T**: Edit files in `/var/www/html/`
❌ **DON'T**: Edit files directly inside the Docker container ❌ **DON'T**: Edit files directly inside the Docker container
❌ **DON'T**: Work on static HTML/CSS files in a workspace ❌ **DON'T**: Work on static HTML/CSS files in a workspace without committing
❌ **DON'T**: Copy files to the server without using git ❌ **DON'T**: Copy files to the server without using git
✅ **DO**: Edit files in `/home/nara/apps/web/` ✅ **DO**: Edit files in `/home/nara/apps/web/out/`
✅ **DO**: Commit changes to git ✅ **DO**: Commit changes to git
✅ **DO**: Use `deploy.sh` for deployment ✅ **DO**: Use `deploy.sh` for deployment
✅ **DO**: Work on the Next.js components (`app/`, `components/`) ✅ **DO**: Test locally before pushing
--- ---
@ -146,29 +148,26 @@ git log --oneline -10
git revert HEAD git revert HEAD
git push origin main git push origin main
# Or reset to specific commit
git reset --hard <commit-hash>
git push origin main --force
# Redeploy # Redeploy
./deploy.sh ./deploy.sh
``` ```
Previous builds are backed up in `out.backup.*` directories.
--- ---
## Cache Headers ## Cache Headers
**HTML pages**: `no-cache, must-revalidate` — browsers always revalidate, ensuring fresh content after deploys. **HTML pages**: `no-cache, must-revalidate` — browsers always revalidate, ensuring fresh content after deploys.
**Static assets** (CSS/JS/images): `public, immutable` with 30-day expiry. Safe because Next.js uses content hashes in filenames (e.g., `2oioldxlp5hov.css`), so new deployments get new URLs. **Static assets** (CSS/JS/images): `public, immutable` with 1-year expiry.
**Nginx config**: `/etc/nginx/sites-available/hatch.surf.conf` **Nginx config**: Built into the Dockerfile.
If users report seeing old content after deployment: If users report seeing old content after deployment:
1. Verify the container is running: `docker ps | grep hatch-web` 1. Verify the container is running: `docker ps | grep hatch-web`
2. Check the HTML has new classes: `curl -s http://localhost:8080 | grep bg-gradient-to-r` 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) 3. Ask user to hard refresh: Ctrl+Shift+R (Chrome/Firefox) or Cmd+Shift+R (Mac)
4. If still cached, check nginx config has `Cache-Control: no-cache, must-revalidate`
--- ---