📘 Deploy Playbook

TrueBalance × TrueCredits Hackathon · June 11–12, 2026 · all teams

1 · Your kit

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-corretto

Getting 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 on

If (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-ingress container (port 80), komodo-periphery, vector (log collection, §7) and the hk-firewall service 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 — pick the lightest option that fits:
  1. Team-private MySQL on your own box (recommended) — full freedom, zero cross-team conflicts, gone with the box:
     docker run -d --name teamdb --restart unless-stopped -p 127.0.0.1:3306:3306 -e MYSQL_ROOT_PASSWORD=hackathon -e MYSQL_DATABASE=app -v ~/teamdb:/var/lib/mysql mysql:8.4
     Reach it at 127.0.0.1:3306 (or as a compose db service, no ports:). The host firewall keeps it team-private by default.
  2. Need existing TB/TC/MF/LG data in it? Seed from the hackathon RDS (endpoint in your team room), no client install needed:
     docker run --rm mysql:8.4 mysqldump -h <rds-endpoint> -u <user> -p'<pw>' --single-transaction --set-gtid-purged=OFF <db> | docker exec -i teamdb mysql -uroot -phackathon app
     Or use the db-stage-clone bundle from Slack: skip setup.sh (laptop helper), run docker compose up --build -d — but first point STAGE_DB_HOST (+ user/password) in its docker-compose.yml at the hackathon RDS; its default targets the real stage DB, which is cut during the event. TC only by default, port :3307.
  3. Shared hackathon RDS — direct use only if you need a DB shared across machines. New tables with an h_ prefix; don't alter/drop what you didn't create. 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 · Slack login for your domain (optional, self-service)

Your domain is public by default. Want it gated behind company Slack? Flip it yourself at hackathon.afinit.dev/authctl — everyone in the workspace (participants, judges, ops) can still get in after signing in.

• Domain toggle: require Slack login ↔ make public — takes effect in seconds.
• Path exceptions (max 5, wildcards */?) get the opposite of the domain setting — e.g. AUTH ON + /api/* = UI locked, API open for callbacks.
• Machines (cron, other boxes, stage services) can always skip auth via port :8443 — same routing, no login, VPC/hackathon source IPs only.
• Every change is logged with your Slack identity and announced — only touch your own team's row. Use the authtest sandbox row to try it out. Sign-in lasts 24 h per domain.
• Path exceptions are convenience, not a security boundary — validate real secrets in your app.

6 · 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.

¹ 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 your team-private MySQL or 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 your team DB / the hackathon RDS endpoint, don't file a bug.

7 · Logs & troubleshooting

Your logs — nearest first: ① docker logs -f app on the box. ② Central log search: everything your containers print to stdout/stderr is collected automatically (nothing to set up) — open stage Kibana, sign in with your own account → Discover → data view "Hackathon team logs" → filter team: <your-slug>. ③ Bare process? Log to ~/app.log (recipe C already does) — collected too. JSON lines become searchable fields; bursts over ~200 lines/s per container are dropped from central search only (docker logs keeps everything).

Still stuck → Slack #temp_hackathon_infra (Neal · David · Dharmendra) · floor support: Sagar +1.