create-hokage-js-app
Version:
🔥 Best CLI tool to create a MERN stack template. Quick, clean, and customizable.
123 lines (83 loc) • 4.14 kB
Markdown
# Deployment Rules
Rules for shipping software safely. Adapt to the project’s platform (Kubernetes, PaaS, serverless, VMs) without inventing new infra that the repo does not use.
## Deployment Principles
- Deployments must be automated from CI/CD — not manual “build on laptop and SCP.”
- Artifacts are immutable: build once, promote the same artifact across environments.
- Every deploy is identifiable by version/git SHA.
- Prefer rolling / blue-green / canary over “stop the world” when the service is user-facing.
- Never invent deployment env vars, cluster names, or service names — use repo/IaC sources of truth.
## Environments
| Env | Purpose | Data |
|-----|---------|------|
| Local | Developer machines | Fake/seed data |
| Dev/Ephemeral | PR previews when available | Non-prod |
| Staging | Pre-prod validation | Anonymized or synthetic |
| Production | Real users | Real data — highest controls |
Rules:
- Prod credentials never in local defaults.
- Schema migrations tested on staging before prod.
- Access to prod deploy is restricted and audited.
## Migrations in Deploys
- Expand/contract: deploy code compatible with both old and new schema during rollout.
- Order:
1. Backward-compatible migration
2. Deploy code
3. Later remove old schema after all instances upgraded
- Avoid migrations that lock large tables during peak traffic.
- Have a rollback plan: code rollback must work with the migrated schema, or forward-fix only with documented steps.
## Health Checks
- `/health` or platform probe: process up (liveness).
- `/ready`: can accept traffic (DB pool, critical deps) — readiness fails remove instance from LB without killing unnecessarily.
- Health endpoints must not require auth and must be cheap.
- Do not deep-check every dependency on every probe if it causes thundering herd — check critically and cache briefly if needed.
## Configuration & Secrets
- Config via env / platform config / secret manager.
- Change prod config through reviewed channels (IaC, change tickets), not ad-hoc SSH edits.
- Feature flags for risky rollouts; default safe.
- Separate image from config — same image, different config per env.
## Zero-Downtime Practices
- Drain connections on shutdown (graceful SIGTERM handling).
- Set termination grace period > longest in-flight request budget.
- Sticky sessions only when required; prefer stateless app tiers.
- Warm caches/JIT carefully on canaries before full rollout.
## Rollbacks
- One-command rollback to previous artifact when schema allows.
- Monitor error rate, latency, saturation during deploy windows.
- Automatic rollback triggers when the platform supports them (failed health, spike in 5xx).
- Communicate customer-facing incidents per on-call process.
## Jobs & Workers
- Deploy workers compatible with queue message versions (tolerant readers).
- Pause or scale consumers carefully during breaking message format changes.
- Idempotent consumers so redeploys/retries are safe.
## Infrastructure as Code
- Infra changes go through PR review like application code.
- No snowflake servers as the long-term state.
- Document manual break-glass steps if they exist; convert to IaC afterward.
## Observability on Deploy
- Emit deploy events/markers in APM/logs.
- Dashboards: golden signals (latency, traffic, errors, saturation).
- Alerts on SLO burn — not only on raw CPU.
## Agent Constraints
- Do not run destructive prod commands (`terraform destroy`, drop DB, force-push release tags) without explicit human instruction.
- Do not modify CI deploy secrets in code.
- When adding a service dependency, update deploy manifests/helm/terraform already used by the project — do not invent a parallel deploy path.
## Deployment Checklist (Inline)
- [ ] Artifact versioned and promoted identically
- [ ] Migration backward compatible with rolling deploy
- [ ] Health/readiness correct
- [ ] Secrets via secret manager; no secrets in images
- [ ] Graceful shutdown handled
- [ ] Rollback path known
- [ ] Dashboards/alerts considered for new critical paths