docs/deploy_guide.md

Deploy Guide — Render.com

Step-by-step deploy TKI-KOS ke Render.com (free tier).

Prerequisites

• Repo public di GitHub: https://github.com/DYmazeh/TKI-KOS
• Render account (sign up free di https://render.com)
• Connect GitHub account ke Render (Account Settings -> Connect GitHub)
• Scraping done -> data ready: data/processed/corpus.json exists
• Indexes done: data/indexes/{tfidf.pkl, bm25.pkl, indobert/}

Critical Question — How to Get Indexes ke Render?

Indexes (TF-IDF pickle, BM25 pickle, IndoBERT embeddings + FAISS) BUTUH ada di Render file system supaya backend bisa load saat startup. Tiga opsi:

Opsi	Pros	Cons
A: Commit indexes ke git	Simplest, auto-deploy via render.yaml	Repo bloat (~30-50MB), GitHub warning di 50MB
B: Build saat deploy	Repo clean	Build time lama (~5 min IndoBERT encode), bisa exceed Render free tier 15-min build timeout
C: External storage (HF Datasets / R2 / GDrive)	Repo clean, fleksibel	Setup complex, butuh download step di lifespan

Rekomendasi untuk student project: Opsi A, asal total data/indexes/ < 50MB. Untuk corpus 3000 listing dengan MiniLM, total biasanya 20-30MB.

Step untuk Opsi A:

1. Temporary remove data/indexes/*.pkl etc dari .gitignore:

   -data/indexes/*.pkl
   -data/indexes/*.index
   -data/indexes/*.bin
   -data/indexes/*.faiss
   -data/indexes/*.npy
   

2. Commit indexes:

   git add data/indexes data/processed/corpus.json
   git commit -m "data: add prebuilt indexes for deploy"
   git push
   

3. NOTE: kalau kamu rebuild indexes (e.g., tune hyperparameter), harus commit ulang. Auto-deploy via render.yaml pickup yang ada di git.

Step 1: Deploy via Blueprint (recommended)

render.yaml di root repo sudah ada — Render baca dan auto-create 3 services.

1. Login ke Render Dashboard
2. New + -> Blueprint
3. Connect repo DYmazeh/TKI-KOS
4. Render parse render.yaml, show preview 3 services:
   • tki-kos-pg (PostgreSQL)
   • tki-kos-backend (Web Service)
   • tki-kos-frontend (Static Site)
5. Click Apply

Render mulai provisioning. Order:

1. PG database (~30 detik)
2. Backend deploy (~5-10 menit — pip install heavy deps termasuk torch/sentence-transformers)
3. Frontend deploy (~2-3 menit — npm install + vite build)

Step 2: Update CORS + API URL (post-deploy)

Setelah deploy selesai, Render kasih URL aktual seperti:

• Backend: https://tki-kos-backend-xxxx.onrender.com
• Frontend: https://tki-kos-frontend-xxxx.onrender.com

Update env vars di kedua service supaya saling kenal:

Backend env: CORS_ORIGINS

1. Render Dashboard -> Backend service -> Environment tab
2. Edit CORS_ORIGINS:

   ["https://tki-kos-frontend-xxxx.onrender.com"]
   

3. Save -> service auto-redeploy

Frontend env: VITE_API_URL

1. Render Dashboard -> Frontend service -> Environment tab
2. Edit VITE_API_URL:

   https://tki-kos-backend-xxxx.onrender.com
   

3. Save -> trigger manual redeploy (env var change perlu rebuild)

Step 3: Run Migrations (DB Schema)

Render PG empty by default. Buka Shell di backend service:

cd /opt/render/project/src/backend
alembic upgrade head

Output expected:

INFO  [alembic.runtime.migration] Running upgrade  -> 001, initial schema

Step 4: Seed Database

Upload data/raw/mamikos.jsonl ke backend service (via Render Shell or curl endpoint kalau ada upload route). Atau, kalau JSONL sudah di-commit:

cd /opt/render/project/src/backend
python -m scripts.seed_db --input ../data/raw/mamikos.jsonl

Output expected:

[load] 1542 listings raw
[filter] 1487/1542 listings pass quality bar
[insert] 1487 listings upserted

Step 5: Verify Deploy

1. Hit health check:

   curl https://tki-kos-backend-xxxx.onrender.com/health
   # -> {"status":"ok","service":"tki-kos-backend"}
   

2. Hit Swagger UI:

   • Browser: https://tki-kos-backend-xxxx.onrender.com/docs
   • Test /search?q=kos putra dekat unila&model=bm25

3. Frontend:

   • Browser: https://tki-kos-frontend-xxxx.onrender.com
   • Should load TKI-KOS search UI
   • Try search "kos putra dekat unila"
   • Verify result cards muncul

Cold Start Mitigation

Free tier backend spin down setelah 15 menit idle. Cold start ~30s + index load ~30-60s = total 60-90s. Bad untuk demo presentasi.

Option A: Keep service warm dengan UptimeRobot

1. Sign up free di https://uptimerobot.com
2. Add new monitor: HTTP(s), URL = https://tki-kos-backend.onrender.com/health, interval = 5 menit
3. Free tier UptimeRobot = 50 monitors, 5-min interval -> total 12 ping/hour cukup

Cost: UptimeRobot ping count towards Render free tier 750 hours/month (720 hours = sebulan penuh). Aman tapi sempit. Kalau idle 14 jam/hari, total ~310 hours/month idle saved.

Option B: Pre-warm sebelum demo

15 menit sebelum presentasi, akses backend URL di browser. Service spin up, warm sampai ~30 menit setelah last request.

Option C: Switch ke Render Starter plan ($7/month)

Always-on, no spin down. Worth it kalau project akan demo berulang kali.

Troubleshooting

Backend deploy fail: "out of memory" saat pip install

Render free tier hanya 512MB RAM. sentence-transformers + faiss-cpu + torch (dependency) total ~600MB di build cache.

Fix: swap requirements.txt untuk separate requirements-prod.txt tanpa heavy deps yang gak digunakan, atau upgrade ke paid plan.

Backend startup timeout

Kalau index loading >5 menit, Render anggap unhealthy dan restart.

Fix:

• Pakai MiniLM (118MB) instead of IndoBERT-base (440MB)
• Precompute FAISS index, commit ke git supaya tinggal load dari disk
• Tambah app.state.tfidf_loaded flag dan return 503 dari /search sampai ready

Frontend can't reach backend (CORS error di browser console)

Fix: verify CORS_ORIGINS di backend env match frontend URL exactly (include https://, no trailing slash). Restart backend.

Postgres free tier expired (after 90 days)

Render kasih warning 7 hari sebelum expire. Backup data:

pg_dump $DATABASE_URL > backup.sql

Create new free PG instance, restore:

psql $NEW_DATABASE_URL < backup.sql

Atau upgrade ke paid plan ($7/month basic) — recommended untuk after course selesai kalau project mau di-keep up.

Monitoring Post-Deploy

Render Dashboard kasih:

• Logs: real-time stream service logs (stdout/stderr)
• Metrics: CPU/RAM/Network usage (free tier limited)
• Events: deploy history, restarts, crashes

Tambah lagi:

• UptimeRobot: external uptime monitor
• Sentry (free tier): error tracking (kalau ada budget waktu di Week 4)

Manual Re-Deploy

Setelah commit baru ke main, Render auto-deploy. Untuk manual trigger:

• Dashboard -> Service -> Manual Deploy -> Deploy latest commit

Useful kalau auto-deploy gagal dan kamu udah fix issue di repo.

Summary Checklist

• PostgreSQL provisioned, connection string captured
• Backend deployed, /health returns 200
• Frontend deployed, accessible via public URL
• CORS_ORIGINS updated dengan frontend URL
• VITE_API_URL updated dengan backend URL
• Migrations run via Shell (alembic upgrade head)
• DB seeded (python -m scripts.seed_db --input ...)
• Indexes available (committed ke git atau download script)
• Search end-to-end works dari frontend
• UptimeRobot configured (kalau perlu warm)
• Screenshot UI live untuk laporan / slide
• URL ditulis di root README