📘 Deploy Playbook
TrueBalance × TrueCredits Hackathon · June 11–12, 2026 · all teams
hackathon-NN) and one public domain
(https://<team-slug>.hackathon.afinit.dev, TLS included).Run anything that listens on port
8080 of your EC2 — it is live on your domain immediately.
No load balancer config, no DNS, no tickets. Until then your domain shows your team's
"warming up" page; the moment something answers on :8080 it becomes your app.1 · Your kit
| EC2 | hackathon-NN (NN = your team number). Verify which box is yours: https://<slug>.hackathon.afinit.dev/__hk |
|---|---|
| Domain | https://<team-slug>.hackathon.afinit.dev → your EC2 port 8080. Find yours & watch it live: hackathon.afinit.dev/preview |
| Spec | 4 vCPU / 15 GB RAM / 50 GB disk · Amazon Linux 2023 · docker + compose + git preinstalled |
| SSH | ssh -i hackathon2026.pem ec2-user@<public-ip> — pem + IP list via Slack / your team room · #temp_hackathon_infra → EC2 inventory thread |
2 · Deploy — pick any recipe
A. Docker (recommended)
docker run -d --name app --restart unless-stopped -p 8080:8080 <your-image>
# app on another internal port? map it: -p 8080:3000 (Node), -p 8080:80 (nginx frontend)B. docker compose — only ONE service publishes 8080 (the front door); internal services talk container-to-container, no ports: needed
services:
web: { build: ., ports: ["8080:3000"], restart: unless-stopped }
api: { build: ./api, restart: unless-stopped } # reach as http://api:<port>C. Bare process
nohup python3 -m uvicorn main:app --host 0.0.0.0 --port 8080 > app.log 2>&1 &
# node/java: sudo dnf install -y nodejs / java-21-amazon-correttoGetting code onto the box: github.com, Docker Hub, npm, pip, Maven all work.
⚠️ GHE (github.balancehero.cc) is NOT reachable from these hosts —
scp your code from your laptop, or mirror to github.com.
3 · Verify (60 seconds)
curl -s localhost:8080/ # 1. app answers locally
curl -s localhost/ # 2. through the on-host ingress
curl -s localhost/__hk # 3. confirms which team box you are onIf (1) works, https://<slug>.hackathon.afinit.dev works.
4 · Rules of the road
- Port 8080 is the only front door. Other published ports are blocked from the internet by the host firewall. Internal ports between your own containers are fine.
- Don't touch the plumbing: the
hk-ingresscontainer (port 80),komodo-periphery, and thehk-firewallservice keep your domain alive. Don't stop or "clean up" these. - HTTPS is terminated for you — your app sees plain HTTP on 8080 (
X-Forwarded-Proto: https). WebSockets work; single requests over ~60 s may be cut by proxy timeouts. - Database: use the temporary hackathon RDS (endpoint in your team room). New tables with an
h_prefix. The DB is discarded after the event. Never point at prod. - Vendor APIs (PayU · Razorpay · CIBIL · Experian): via mock-api-proxy — setup in your team room.
- Push your code to a remote you keep — EC2 and DB are reclaimed after the event.
5 · What you can (and can't) reach from your box
Verified from all 30 boxes — where a login exists, the network is open but you still sign in with your own account.
| ✅ Reachable | Address | Note |
|---|---|---|
| Kibana — stage app logs | stage-applog-kibana.balancehero.cc | login required |
| Kibana — prod app logs | prod-applog-kibana.balancehero.cc | temporary route¹ · prod — look, don't touch |
| JupyterHub | jupyterhub.balancehero.cc | temporary route¹ · login required |
| Nexus (private Java deps) | nexus.truebalance.cc:443 | for building TB/TC backend services |
| stage infra services | memcached · egress-proxy etc. | VPC direct — for stage-stack replicas |
| mock-api-proxy | endpoint in your team room | PayU · Razorpay · CIBIL · Experian mocks |
| public internet (egress) | — | unrestricted — npm, pip, Docker Hub, github.com |
| ❌ Not reachable (by design) | Why |
|---|---|
GHE (github.balancehero.cc) | IP allowlist — use github.com or scp (§2) |
| prod services / prod DB endpoints | Policy: stage only, no prod data (prod Kibana is the single read-only exception) |
¹ Temporary route set up for the event — if these stop responding, don't debug it, ping
#temp_hackathon_infra (your domain, DB and stage Kibana are unaffected).
Stage DBs: directly reachable today, but use the temporary hackathon RDS (§4) — direct
access to the real stage DBs is being cut intentionally; if a direct DB connection stops
working, switch to the hackathon RDS endpoint, don't file a bug.
6 · Troubleshooting
| Symptom | Fix |
|---|---|
| Domain still shows "warming up" page | Nothing on 8080: curl localhost:8080, docker ps, docker logs app |
| localhost:8080 works, domain doesn't | Wrong box — curl localhost/__hk must show your slug |
| App was live, team page is back | App crashed (the page is the automatic fallback) — docker logs app |
| "port already in use" on 8080 | Your own old process holds it: ss -tlnp | grep 8080. Port 80 busy is normal (ingress — leave it) |
| Long request dies ~60 s | Proxy timeout — stream, poll, or use WebSocket |
| Can't clone from GHE | Expected (blocked) — use github.com or scp |
Still stuck → Slack #temp_hackathon_infra (Neal · David · Dharmendra) · floor support: Sagar +1.