Skip to main content
You will take an existing Express API, with a Dockerfile and a docker-compose.yml that runs Postgres, and give it dev, staging and prod environments on Reliant hosting with a managed Postgres. No app file changes: Forge reads the Dockerfile and compose file and writes its declarations beside them. The same works for Django, Rails, Spring or Go, because Forge deploys the image your Dockerfile builds and never compiles your code. Escape hatches describes the tiers after this one.

Before you begin

  • Reliant v1.21.3 or later, signed in. Inside Reliant, Forge runs as reliant forge. --kind app needs Forge v1.5.0 or later; this guide was run at v1.6.1-0.20261115024114-0ab7c562e817, the Forge embedded in Reliant v1.21.3.
  • A git repository holding the app, with a root Dockerfile that builds on its own, and Docker for local runs.
  • Billing on your organization for the deploy step. A hosted workload or database is not on the free tier.
1

Preview what Forge would write

In the app’s root, --dry-run prints what it detected and every file it would write, and writes nothing:
terminal
Output (trimmed)
With no compose file, it reads the port from EXPOSE or ENV PORT and runs dev from your dev script, Procfile or CMD, beside a local Postgres.
2

Adopt the app

terminal
Output
The only edit to an existing file is a # --- forge --- block appended to .gitignore. Commit the new files, kcl.mod.lock included, so a deploy starts from a clean tree.
3

Review the declarations

deploy/kcl/workloads.k declares the app once. Each line marked # check: is a guess; read it:
deploy/kcl/workloads.k
staging/main.k and prod/main.k bind both workloads to hosting, give each env its own forge.ManagedDatabase, and make each credential the compose file reads from a variable (here SESSION_SECRET) a forge.ManagedSecret. Check the app’s fallbacks too: SECRET || "dev" is a production hole if the secret is never set.
4

Build, render and lint

A deploy runs docker build on the Dockerfile and its context alone, so prove that first. Then render prod, which is the dry run of a deploy:
terminal
Output (trimmed)
5

Run it locally

Dev runs your compose file. Set every variable it reads first:
terminal
Output (trimmed)
Stop it with reliant forge env down dev. If env up fails, see Troubleshooting.
6

Set the secrets and deploy staging

secret set reads the value from stdin and creates the hosted env on first use (Secrets). --yes approves the plan the deploy prints:
terminal
Output (trimmed)
The migration job ran before the API started. Without billing, the deploy exits 7 and prints the link to set it up. To promote the same image to prod, set prod’s secrets the same way, then run reliant forge env deploy prod --from staging.
7

Verify the deploy

Write and read through the staging URL, then ask for the workloads’ health:
terminal
Output
reliant forge obs check staging --wait --json returned exit 2, reason_code: no_request_telemetry: the app sends no traces yet, so the release is not proven good. See obs check exit codes.
8

Clean up

If this was a trial, delete the hosted env. It removes the workloads and the managed database’s data, and keeps the release images:
terminal

Stop earlier: monitor or record only

Forge does not have to deploy the app. Two lighter steps need no forge.yaml and no deploy/kcl:
  • Monitoring only. reliant forge obs init prod --project notes-api registers the env, mints a telemetry ingest token and prints the OTEL_* variables to set where the app runs. A person must run it; from an agent’s shell it is refused (not a machine credential).
  • Recording deploys. reliant forge release record --env prod --version v1.4.0, after your own CI deploys, gives monitoring a deploy marker. Reliant cloud does not accept recorded releases yet: it refuses with reason: record_only_releases_disabled and writes nothing.
release record refuses an env that deploy/kcl binds to hosting, because Forge deploys that one. Pick one path per env.

What this does not do

  • It does not instrument the app. Hosting sets OTEL_EXPORTER_OTLP_ENDPOINT and OTEL_SERVICE_NAME; until an OpenTelemetry SDK reads them, obs check stays INCONCLUSIVE.
  • It does not roll back. You recover by deploying an earlier release, and migrations run before every rollout, so keep them backward-compatible.
  • It does not write CI. Releases and promotion covers deploying from a pipeline.

Troubleshooting

You ran project new --in-place without --kind. It refuses rather than write a Go server into your app, and nothing was written. Add --kind app, or --kind site for a Vite or Next.js app with no server.
The compose file reads a variable that is not set, and env up dev mistook compose’s warning for a container name. Export every ${VAR} the compose file uses, then run env up dev again. The db container from the failed run may survive env down dev; remove it with docker rm -fv <name>.
env up dev waits for services to be healthy, and a one-shot migration container that exits counts as a failure when another service lists it under a plain depends_on. Write depends_on: {migrate: {condition: service_completed_successfully}} instead.
The deploy is queued on billing. Open the link it prints, set up billing, and deploy again.

Next steps

Send OpenTelemetry from any app

Turn the INCONCLUSIVE verdict into real request, error and latency data.

Deploy a Go API with managed Postgres

The same release flow for a Forge-built service.

Managed Postgres

What the managed database gives each env, and what it costs.