Bounty Submission: Universal One-Click Deployment (Docker + K8s + Tilt) for FinMind

[chengyixu]

/claim #144

Summary

Production-grade, universal one-click deployment system for FinMind covering all 12+ mandatory platforms with a single dispatcher script.

./deploy/scripts/deploy.sh <platform>

39 files, 3,411 lines added, 0 deletions — purely additive, no existing code modified.

What's Included

Kubernetes (Production-Grade Helm Chart — 15 Templates)

Template	Purpose
backend.yaml	Deployment with init containers (wait-for-postgres, wait-for-redis, init-db), rolling updates, Prometheus annotations
frontend.yaml	Deployment with rolling updates, health probes
postgres.yaml	StatefulSet-like deployment with PVC, readiness/liveness probes
redis.yaml	Deployment with redis-cli health checks
nginx.yaml	Reverse proxy with security headers, upstream config
hpa.yaml	Backend 2-10 replicas (CPU+memory), Frontend 2-6 replicas, scale-down stabilization
networkpolicy.yaml	Zero-trust: 5 policies (postgres, redis, backend, nginx, frontend)
pdb.yaml	PodDisruptionBudget for backend and frontend
ingress.yaml	TLS-ready with cert-manager, rate limiting
secrets.yaml	Kubernetes Secret with all credentials
configmap.yaml	Non-sensitive configuration
serviceaccount.yaml	Dedicated ServiceAccount
namespace.yaml	Namespace with labels
_helpers.tpl	Template helpers, label generators, configmap checksums
values.yaml	200+ configurable values with sensible defaults

Tilt (Local K8s Dev with Live Reload)

• Backend: Python file sync + gunicorn --reload — no Docker rebuild needed
• Frontend: Vite HMR via file sync — instant updates
• Dependency ordering: postgres -> redis -> backend -> frontend
• Port forwarding: Backend :8000, Frontend :5173
• Manual trigger buttons: Run backend tests, frontend tests, smoke tests
• Safety: Refuses to run against non-local K8s contexts

Cloud PaaS Platforms (6)

Platform	Config	Type
Railway	railway.toml	Full-stack
Heroku	Procfile + heroku.yml + app.json (1-click deploy ready)	Full-stack
Render	render.yaml Blueprint (auto-provisions DB + Redis)	Full-stack
Fly.io	Backend + Frontend fly.toml with health checks, auto-scaling	Full-stack
DigitalOcean App Platform	do-app-spec.yaml with managed DB + Redis	Full-stack
DigitalOcean Droplet	One-line setup script (curl | bash)	Full-stack

Cloud Providers (4)

Platform	Config	Deploy Script
AWS ECS Fargate	Task definition + SSM secrets	deploy.sh (build, push to ECR, deploy)
AWS App Runner	Service YAML	CLI command
GCP Cloud Run	Knative service YAML	deploy.sh (Cloud Build, Cloud SQL, Memorystore)
Azure Container Apps	Container app YAML	deploy.sh (ACR, PostgreSQL, Redis)

Frontend CDN (2)

Platform	Config	Features
Netlify	netlify.toml	SPA fallback, API proxy, security headers, asset caching
Vercel	vercel.json	SPA rewrites, security headers, immutable asset caching

Infrastructure

• Universal deploy script: ./deploy/scripts/deploy.sh <platform> with pre-flight checks
• Smoke test suite: Validates all acceptance criteria (frontend, backend health, DB/Redis, auth flows, core modules)
• CI/CD pipeline: GitHub Actions for automated Docker image builds to GHCR
• Deployment guide: Comprehensive documentation with architecture diagram, per-platform instructions, troubleshooting

File Structure

Tiltfile                                                # Local K8s dev workflow
.github/workflows/deploy.yml                           # CI/CD pipeline
deploy/
  DEPLOY-GUIDE.md                                       # Comprehensive deployment guide
  scripts/
    deploy.sh                                           # Universal one-click dispatcher
    smoke-test.sh                                       # Runtime acceptance test suite
  helm/finmind/                                         # Production Helm chart
    Chart.yaml, values.yaml
    templates/ (15 files)
  platforms/
    railway/railway.toml
    heroku/{Procfile, heroku.yml, app.json}
    render/render.yaml
    flyio/{backend,frontend}/fly.toml
    digitalocean/{app-platform/do-app-spec.yaml, droplet/setup.sh}
    aws/{ecs-fargate/{task-definition.json, deploy.sh}, app-runner/apprunner.yaml}
    gcp/{cloudrun.yaml, deploy.sh}
    azure/{container-app.yaml, deploy.sh}
    netlify/netlify.toml
    vercel/vercel.json

Runtime Acceptance Criteria

Each deployment configuration ensures:

• Frontend reachable (React SPA served by Nginx)
• Backend health endpoint responsive (/health)
• DB + Redis connected (health check validates connectivity)
• Auth flows working (JWT secret configured, register/login endpoints)
• Core modules working (expenses, bills, reminders, dashboard, insights)

The smoke test script (deploy/scripts/smoke-test.sh) programmatically validates all of these.

Key Differentiators vs Other Submissions

1. Init containers: Backend waits for postgres+redis before starting, then auto-runs init-db
2. ConfigMap checksums: Pods automatically restart when configuration changes
3. NetworkPolicy: True zero-trust — 5 granular policies controlling all inter-service traffic
4. Scale-down stabilization: HPA prevents flapping with 300s stabilization window
5. Lifecycle hooks: Pre-stop sleep ensures graceful connection draining
6. CI/CD integration: GitHub Actions pipeline builds and pushes images on every merge
7. Smoke tests: Automated acceptance criteria validation, runnable against any deployment
8. Tilt safety: Refuses to run against production K8s contexts

Fixes #144