45559c0e-d9d4-4741-94b7-ca25b55059d3
Forgeon Docs

Documentation, guides, and patterns to help you build on Forgeon — from your first deploy to running serious infrastructure.

Deployments

Forgeon deployments: environments, rollouts, runtime state, and operational controls.

Last updated: 2026-03-17

Forgeon deployments are built around environments, a build pipeline, and runtime state. Use this page as the operating playbook for shipping changes safely from preview to production.

flowchart LR
  A[Intake] --> B[Build]
  B --> C[Artifact]
  C --> D[Runtime start]
  D --> E[Health checks]
  E --> F[Route traffic]

The deployment model

  • Environment — prod / uat / qa / staging / dev / preview
  • Deployment — a build artifact + runtime config for an env
  • Runtime — running container(s) with live traffic state

Recommended promotion flow

  1. Deploy to preview for each PR and run smoke checks.
  2. Promote the same commit to staging and validate integrations.
  3. Deploy to prod only after health + domain checks pass.
  4. Keep previous healthy deployment available for fast rollback.

What you can control per environment

  • Build system (Template / Nixpacks / Buildpacks)
  • Build and start commands
  • Environment variables per env
  • Rollouts and restarts
  • Domains and SSL

Pre-deploy checklist (2 minutes)

  • Confirm target branch and commit SHA are correct.
  • Validate required env vars exist for the target environment.
  • Ensure app listens on PORT and binds 0.0.0.0.
  • Check domain mapping and SSL state for prod.
  • Review latest usage/quota so deploy is not blocked.

Runtime states and what they mean

| State | Meaning | Action | | --- | --- | --- | | building | Source is being built into artifact | Wait for build logs | | starting | Runtime booting and health-checking | Verify startup command | | running | Healthy and serving traffic | Observe metrics + errors | | idle | Scale-to-zero / no recent traffic | Hit domain to wake | | degraded | Partial readiness or repeated failures | Check logs + dependencies | | failed | Build or runtime start failed | Use error table below |

Common deploy failures (fast diagnosis)

| Symptom | Most likely cause | Fix | | --- | --- | --- | | Build fails early | Missing lockfile / bad build command | Pin command and lock dependency manager | | Deploy succeeds, URL unreachable | App bound to localhost only | Bind to 0.0.0.0:$PORT | | Runtime flips starting -> failed | Startup command exits or health check mismatch | Verify start command + readiness path | | quota_exceeded / build_minutes | Plan quota reached | Upgrade plan or reduce usage | | Domain opens placeholder page | Domain not attached to active env/deploy | Re-attach domain to correct environment |

Rollback policy you should adopt

  1. Roll back to the last healthy deployment immediately if error rate spikes.
  2. Freeze new deploys until root cause is identified.
  3. Create a short incident note with: bad commit SHA, start time, and fix.
  4. Re-deploy with explicit verification checklist.

Post-deploy verification

  • Open production URL and verify HTTP 200.
  • Confirm correct release version/build hash in app footer or logs.
  • Check p95 latency and 5xx rate for 5-10 minutes.
  • Validate one critical user path end-to-end.

Learn next