monkilabs/deployment-infrastructure

Deployment Infrastructure

See deployment-config.md for full architecture, env vars, cron jobs, caching headers.

Environment Variables

Layering & Precedence

.env (defaults, committed) → .env.local (git-ignored) → .env.production / .env.preview → Platform-injected (highest).

Startup Validation

import { z } from 'zod';

const envSchema = z.object({
  DATABASE_URL: z.string().url(),
  API_SECRET: z.string().min(32),
  PUBLIC_SITE_URL: z.string().url(),
  CRON_SECRET: z.string().min(16),
  NODE_ENV: z.enum(['development', 'production', 'test']).default('development'),
});

export const env = envSchema.parse(process.env);

Naming

Prefix: PUBLIC_*/NEXT_PUBLIC_* (browser-safe), SECRET_*/*_SECRET (server-only). SCREAMING_SNAKE_CASE. Gitignore .env.local, .env.*.local.

CI/CD Pipeline

Branch deployment: main → Production (auto) | feature/*, fix/* → Preview (auto)

Stages (in order): Install (--frozen-lockfile), Lint, Test (unit + integration + coverage), Build (production build), Deploy

Cron auth:

export async function GET(request: Request) {
  const authHeader = request.headers.get('authorization');
  if (authHeader !== `Bearer ${process.env.CRON_SECRET}`)
    return new Response('Unauthorized', { status: 401 });
  return Response.json({ ok: true });
}

Caching Strategy

| Asset Type | Cache-Control Header | |---|---| | Hashed static assets (JS, CSS) | public, max-age=31536000, immutable | | Images / fonts | public, max-age=31536000, immutable | | Favicon / manifest | public, max-age=86400 | | HTML pages (SSG) | public, max-age=0, must-revalidate | | API responses | private, no-cache | | Prerendered pages (ISR) | public, s-maxage=3600, stale-while-revalidate=86400 |

Apply via framework headers() config or CDN rules.

Security Headers

Load security-hardening skill for full CSP inventory, header configuration.

Release Process

1. Audit — lint, test, build; git diff since last tag; verify no draft PRs
   • Gate: all commands exit 0
2. Changelog — generate from commits; categorize (Features, Fixes, Breaking); include migration notes
3. Tag — semver tag; update version references
4. Verify — curl -sI https://example.com | grep -E 'HTTP|Strict' — smoke-test production URLs; monitor error rates
   • Gate: homepage returns 200; headers correct
   • Fail → rollback immediately

Rollback

Prefer platform rollback (promote last good deploy). Fallback: git revert -m 1 HEAD Prefer platform rollback (promote last good deploy). Fallback: git revert -m 1 HEAD && git push.Prefer platform rollback (promote last good deploy). Fallback: git revert -m 1 HEAD && git push. git push.

1. Roll back → 2. Smoke-test (curl -sI) → 3. Confirm 200 + correct behavior → 4. If still broken, escalate
2. Notify team; create post-mortem ticket

Anti-Patterns

| Anti-Pattern | Fix | |---|---| | Hardcoding secrets | Env vars + Zod startup validation | | Skipping preview deployments | Deploy every branch to preview | | Cache-Control: no-store everywhere | Per-asset cache durations (see table) | | Disabling security headers "temporarily" | Keep strict; document exceptions | | Builds without --frozen-lockfile | Always use --frozen-lockfile in CI |