Our server: folders, ports, users and the production switch for the real VPS are in server.md. The paths below are the pipeline's defaults.
Two sites run on the same VPS, built from the same code:
| Development | Production | |
|---|---|---|
| Address | https://dev.zigexconnect.com |
https://zigexconnect.com |
| Deploys when | anything is pushed to zigex (the main branch) |
a version tag is pushed (v1.0.1) |
Version shown at /api/health |
1.0.1-dev.3f2a9c1 (version + commit) |
1.0.1 |
| On the VPS | /home/zigex/apps/zigex-dev, PM2 zigex-dev, port 3002 (our server) |
/home/zigex/apps/zigex, PM2 zigex, port 3200 |
| Secrets | /home/zigex/apps/zigex-dev/shared/.env |
/home/zigex/apps/zigex/shared/.env |
| Search engines | blocked (noindex + disallow-all robots.txt) | indexed |
Both use the same backend (api.zigexconnect.com) unless you set a different BACKEND_URL for development. Actions on the development site are real: an application sent there reaches the company. Use test accounts.
feature branch ──PR──► CI (type check, build, audit)
merge to zigex ──► Deploy → development (dev.zigexconnect.com)
test on dev, then: Actions → Release → Run workflow (patch / minor / major)
Release: version + changelog date → tag v1.0.1 ──► Deploy → production (zigexconnect.com)
each deploy: build on GitHub → upload → switch → health check → automatic rollback if unhealthy
| # | Check | If it fails |
|---|---|---|
| 1 | You approve the run (if production has a required reviewer) |
Nothing happens |
| 2 | It's a version tag matching package.json |
Stops; live site untouched |
| 3 | The same commit passed CI and deployed successfully to the development site (waits up to 25 minutes, because pushing a version starts both) | Stops; live site untouched |
| 4 | The build succeeds | Stops; live site untouched |
| 5 | After switching: /api/health reports the new version |
The previous release comes back automatically |
| 6 | Smoke test: sign-in, Explore, a real opportunity page and the stylesheet open without the error screen (deploy/smoke.sh) |
The previous release comes back automatically. If the backend itself is down, it keeps the release and warns instead: rolling back wouldn't fix the backend |
| 7 | https://zigexconnect.com/api/health shows the new version through the real domain |
The run is marked failed (DNS or Nginx problem) |
Still not covered: anything that passes these checks but behaves wrong (a button that does the wrong thing). That's what testing on the development site is for.
Emergency fix without the development check: Actions → Deploy → Run workflow → production, the tag, and tick Emergency only. Use rarely: it skips check 3.
Run the smoke test by hand any time: deploy/smoke.sh https://zigexconnect.com (or the dev address).
| File | What it does |
|---|---|
.github/workflows/ci.yml |
Every pull request and push: install, type check (report only for now), build, audit |
.github/workflows/deploy.yml |
Picks the environment, builds, packages, uploads, switches, checks the live site, creates the GitHub Release (production) |
deploy/remote-deploy.sh |
On the VPS: unpack, switch current, restart PM2, require /api/health to report the new version, roll back if not, keep 3 releases |
deploy/smoke.sh |
Opens the main pages and checks they work; exit 1 = release broken, 2 = backend down |
deploy/rollback.sh |
On the VPS: switch back by hand |
deploy/ecosystem.config.cjs |
PM2 config for either site (APP_NAME, APP_PORT, APP_DIR) |
deploy/nginx/zigex.conf, deploy/nginx/zigex-dev.conf |
Nginx sites |
app/api/health/route.ts |
GET /api/health → { status, version } |
lib/app-env.ts |
NEXT_PUBLIC_APP_ENV (production / development), used for noindex |
zigexconnect.com's DNS is at Hostinger (nameservers ns1/ns2.dns-parking.com). In Hostinger → Domains → DNS / Nameservers, add:
| Type | Name | Points to |
|---|---|---|
| A | dev |
your VPS IP |
| A | @ |
your VPS IP (if production isn't already pointed there) |
| CNAME | www |
zigexconnect.com |
Check: nslookup dev.zigexconnect.com returns the VPS IP (can take up to an hour).
Assumes Ubuntu with Nginx. Run as a sudo user.
# Node 22 (matches .nvmrc) and PM2
curl -fsSL https://deb.nodesource.com/setup_22.x | sudo -E bash -
sudo apt-get install -y nodejs
sudo npm install -g pm2
# A deploy user that owns both sites
sudo adduser --disabled-password --gecos "" deploy
for site in zigex zigex-dev; do
sudo mkdir -p /var/www/$site/{releases,shared/logs,incoming}
done
sudo chown -R deploy:deploy /var/www/zigex /var/www/zigex-dev
# Secrets per site (start dev from a copy of production's, then change what differs)
sudo -u deploy cp /path/to/production.env /var/www/zigex/shared/.env
sudo -u deploy cp /path/to/production.env /var/www/zigex-dev/shared/.env
sudo chmod 600 /var/www/zigex/shared/.env /var/www/zigex-dev/shared/.env
# PM2 comes back after a reboot
sudo env PATH=$PATH pm2 startup systemd -u deploy --hp /home/deployNginx and HTTPS: follow the comments at the top of each file in deploy/nginx/, then:
sudo certbot --nginx -d zigexconnect.com -d www.zigexconnect.com
sudo certbot --nginx -d dev.zigexconnect.comOptionally password-protect the development site (instructions in deploy/nginx/zigex-dev.conf).
Firewall: only SSH, 80 and 443: sudo ufw allow OpenSSH && sudo ufw allow 'Nginx Full' && sudo ufw enable. Ports 3000 and 3100 stay private (the apps listen on 127.0.0.1).
SSH key for GitHub Actions (on your own machine):
ssh-keygen -t ed25519 -f zigex_deploy -C "github-actions-deploy" -N ""
ssh-copy-id -i zigex_deploy.pub deploy@YOUR_VPS
ssh-keyscan -p 22 YOUR_VPS # output → VPS_KNOWN_HOSTS secretOther services that need the dev address:
- Google sign-in: Google Cloud Console → Credentials → the OAuth web client → add
https://dev.zigexconnect.comto Authorized JavaScript origins. - Backend: browser calls go through the app's own
/api/v1, so no CORS change is needed.
Settings → Environments: create development and production. Add yourself as a required reviewer on production so every release waits for your click.
Secrets (repository level, shared by both):
| Secret | Value |
|---|---|
VPS_HOST |
VPS IP or hostname |
VPS_USER |
deploy |
VPS_PORT |
SSH port (optional, default 22) |
VPS_SSH_KEY |
Contents of zigex_deploy (private key) |
VPS_KNOWN_HOSTS |
Output of ssh-keyscan |
Variables: set shared values at repository level, and the ones that differ on each environment (environment values win):
| Variable | development | production |
|---|---|---|
NEXT_PUBLIC_SITE_URL |
https://dev.zigexconnect.com |
https://zigexconnect.com |
FRONTEND_URL |
https://dev.zigexconnect.com |
https://zigexconnect.com |
VPS_APP_DIR, APP_NAME, APP_PORT |
optional (defaults /var/www/zigex-dev, zigex-dev, 3100) |
optional (defaults /var/www/zigex, zigex, 3000) |
BACKEND_URL |
repo level: https://api.zigexconnect.com (override here for a staging backend) |
repo level |
NEXT_PUBLIC_ADMIN_APP_URL, NEXT_PUBLIC_GOOGLE_CLIENT_ID, NEXT_PUBLIC_VAPID_PUBLIC_KEY, NEXT_PUBLIC_SANITY_PROJECT_ID, NEXT_PUBLIC_SANITY_DATASET, NEXT_PUBLIC_EMAILJS_SERVICE_ID, NEXT_PUBLIC_EMAILJS_PUBLIC_KEY, NEXT_PUBLIC_EMAILJS_AI_WAITLIST_TEMPLATE_ID |
repo level | repo level |
NEXT_PUBLIC_APP_ENV is set by the workflow from the environment; don't set it by hand.
Server-only secrets (JWT_SECRET, GMAIL_*, EMAILJS_PRIVATE_KEY, RESEND_API_KEY, SANITY_WEBHOOK_SECRET…) live only in each site's shared/.env on the VPS. JWT_SECRET must match the admin app's on the same environment (attendance QR codes).
Branches: zigex is the main and deployment branch. Protect it (Settings → Branches): pull request required, CI must pass. Do work on short-lived branches (feat/…, fix/…) and merge them into zigex through pull requests.
- Merge to
zigex→ development updates by itself in a few minutes. Checkhttps://dev.zigexconnect.com/api/healthshows the new commit. - Test on dev with test accounts (phone sign-in, Explore, apply, My applications, notifications, Edit profile).
-
Development is green and tested. Write the changes for students under the top section of
CHANGELOG.md(## Unreleased, or the version marked not released yet) as you go. -
Confirm the backend items this release depends on are live (check the live API, not messages).
-
Actions → Release → Run workflow, and choose the version:
keepfor 1.1.0 (package.jsonis already 1.1.0), thenpatch(fixes),minor(new features) ormajor(breaking, rare). Release:- checks that
zigex's latest commit passed CI and is on the development site (stops otherwise), - sets the version in
package.json, dates its section ofCHANGELOG.md, - commits that to
zigex, tagsv1.2.3, and starts Deploy for production.
Watch the Deploy run (after your approval if you set reviewers). It also creates the GitHub Release from the changelog.
From a terminal instead: date the changelog,
npm version patch|minor|major(for 1.1.0:git tag v1.1.0),git push origin zigex --follow-tags. - checks that
-
First time only (1.1.0), before step 3:
zigexconnect.comstill runs the old app; switch it over as described in server.md, or the deploy's final check ofzigexconnect.com/api/healthfails. -
When the run is green,
https://zigexconnect.com/api/healthshows the version. Open the site on a phone. -
For the next hour:
ssh zigex@169.58.25.57, thenpm2 logs zigex.
Redeploy by hand (e.g. after changing a site's shared/.env): Actions → Deploy → Run workflow → pick the environment and the ref (v1.0.1 for production). For an .env change alone, pm2 restart zigex (or zigex-dev) on the VPS is enough.
Deploys roll back by themselves when the new release fails its health check. By hand (a bug the health check can't see):
ssh zigex@169.58.25.57
APP_DIR=~/apps/zigex APP_PORT=3200 ~/apps/zigex/current/deploy/rollback.sh # production: previous release
APP_DIR=~/apps/zigex APP_PORT=3200 ~/apps/zigex/current/deploy/rollback.sh 1.1.0 # production: a specific version
APP_DIR=~/apps/zigex-dev APP_NAME=zigex-dev APP_PORT=3002 \
~/apps/zigex-dev/current/deploy/rollback.sh # developmentThe last 3 releases of each site are kept in releases/<version>_<timestamp>. Then fix forward with a new patch version.
| Symptom | Check |
|---|---|
| "Production deploys need a version tag" | You ran production on a branch: use a tag (v1.0.1) |
| "Tag doesn't match package.json" | Use npm version … instead of tagging by hand |
| Host key error at "Upload and switch" | VPS_KNOWN_HOSTS is out of date: run ssh-keyscan again |
| "Missing …/shared/.env" | Create that site's .env (step 2) |
| Health check fails, release rolled back | pm2 logs zigex / pm2 logs zigex-dev; usually a missing variable in shared/.env |
"doesn't report version" at "Check the live site" |
The deploy worked on the VPS but the domain doesn't reach it: DNS (step 1) or the Nginx site |
| Google sign-in fails only on dev | Add the dev origin in Google Cloud Console (step 2) |
| Old version after a deploy | The PWA service worker: reload once or reopen the installed app; check /api/health |
| 502 Bad Gateway | The app isn't running: pm2 status |