01 — Overview: How Hosting Works
Spec version: 1.2 (based on DevOps PDF spec v1.0 with corrections — see SPEC-REVIEW.md at the repo root; v1.2 adds the migration path for existing apps and the guide-update check)
Audience: app teams using AI assistants, and the AI assistants themselves.
Policies evolve. AI assistants must check for guide updates at the start of every session:
GET /api/spec-versionon the hosted guide site (orgit pullthe reference repo). The newest spec version always wins. Details inAI-ASSISTANT-GUIDE.md, Step 0.
The pipeline, end to end
- Your code is packaged into a container image — a self-contained box with your app and everything it needs, built with Docker from
dockerfiles/Dockerfile. - The image is stored in ECR (AWS Elastic Container Registry) — the company's private Docker registry.
- The image is deployed to our Kubernetes cluster — which runs at least two copies of your app at all times, so if one crashes the other keeps serving users.
- Everything is automated — every push to
maintriggers a GitHub Actions pipeline that builds, pushes, and deploys. No manual steps.
Requirements at a glance
| ID | Requirement | Priority |
|---|---|---|
| REQ-01 | App packaged as a Docker container that runs on Linux (linux/amd64) |
Critical |
| REQ-02 | dockerfiles/Dockerfile provided and builds successfully |
Critical |
| REQ-03 | Linux base image only — no Windows containers | Critical |
| REQ-04 | App is stateless; supports multiple identical copies simultaneously | Critical |
| REQ-05 | kubernetes/deployment.yaml with replicas: 2 minimum |
Critical |
| REQ-06 | kubernetes/service.yaml to expose the application |
Critical |
| REQ-07 | .github/workflows/ci.yml — build, push to ECR, deploy to the K8s cluster on merge to main |
Critical |
| REQ-08 | PostgreSQL only — no other database engine | Critical |
| REQ-09 | Zero hardcoded secrets; all credentials via env vars from K8s Secrets | Critical |
| REQ-10 | Project follows the defined folder structure exactly | Critical |
| REQ-11 | source/README.md listing every environment variable |
Required |
| REQ-12 | /healthz endpoint returning HTTP 200 within 2 seconds when healthy |
Critical¹ |
¹ Upgraded from "Strongly Recommended" in spec v1.0: the required liveness/readiness probes in deployment.yaml depend on this endpoint existing, so it is effectively mandatory.
Reading order
| Guide | Covers |
|---|---|
02-folder-structure.md |
The exact repository layout |
03-dockerfile.md |
Building the container image |
04-kubernetes.md |
Deployment, Service, ConfigMap manifests |
05-cicd-pipeline.md |
The GitHub Actions workflow |
06-database.md |
PostgreSQL rules and safe migrations |
07-secrets-and-config.md |
Secrets, ConfigMaps, environment variables |
08-stateless-and-health.md |
Statelessness, graceful shutdown, health endpoints |
09-onboarding-checklist.md |
Pre-submission checklist and SLA |
10-migrating-existing-apps.md |
Already built your app? The phase-by-phase retrofit path |