> ## Documentation Index
> Fetch the complete documentation index at: https://docs.reliantlabs.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Deploy an existing app from its Dockerfile, in any language

> Adopt an Express, Django or Rails app where it stands: Forge reads its Dockerfile and compose file, writes the deploy config, and ships it to Reliant hosting.

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](https://docs.reliantlabs.io/hosting/overview.md) 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](https://docs.reliantlabs.io/forge/deploy/escape-hatches.md#adopt-an-app-that-already-exists) 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:

```bash terminal theme={null}
reliant forge project new --in-place --kind app --dry-run
```

```text Output (trimmed) theme={null}
Detected:
  - Postgres: compose service "db" (postgres:16) → a managed Postgres on staging and prod; dev keeps the compose service
  - workload api (service): compose service "api", builds Dockerfile, port 3000, reads DATABASE_URL
  - migrations: npm run migrate (compose service "migrate") → job migrate, before every rollout
Where it runs:
  - dev: docker-compose.yml, through docker compose, as before
  - staging and prod: Reliant hosting (forge.OnHosted), built once and promoted by digest
```

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**

```bash terminal theme={null}
reliant forge project new --in-place --kind app --name notes-api
git status --short
```

```text Output theme={null}
✅ App 'notes-api' adopted at /home/you/notes-api
   wrote forge.yaml, deploy/kcl/kcl.mod (+ its empty kcl.mod.lock), deploy/kcl/workloads.k, deploy/kcl/{dev,staging,prod}/main.k — no Go, none of the app's files changed
 M .gitignore
?? deploy/
?? forge.yaml
```

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:

```python deploy/kcl/workloads.k theme={null}
api = fw.Workload {
    name = "api"
    kind = "service"
    image = "api"
    build = forge.DockerBuild {dockerfile = "Dockerfile", context = "."}
    ports = [fw.Port {name = "http", port = 3000, expose = True}]
    env = {PORT = "3000"}
    probes = tiers.Probes {tcp = True}
}

migrate = fw.Workload {
    name = "migrate"
    kind = "job"
    image = api.image
    build = api.build
    command = ["npm", "run", "migrate"]  # check: compose service "migrate"'s command
    env = api.env
    before = [fw.BEFORE_ALL]
}
```

`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:

```bash terminal theme={null}
docker build .
reliant forge env render prod
reliant forge lint
```

```text Output (trimmed) theme={null}
[render] prod — 3 object(s) of 0 rendered
[render]   cluster:   hosted                   3 object(s)
hosted (published to the control plane, not applied):
  migrate (job): …
  api (service): …
  notes (database)
…
✅ 11 gating linter(s) passed; 2 skipped (contract linter, migration safety lint)
```

**5. Run it locally**

Dev runs your compose file. Set every variable it reads first:

```bash terminal theme={null}
export SESSION_SECRET=dev-only
reliant forge env up dev
curl -s -X POST -H 'Content-Type: application/json' -d '{"body":"hello from dev"}' http://localhost:3000/notes
```

```text Output (trimmed) theme={null}
│ Compose services
│  ● db :5432   http://localhost:5432  up
│  ● api :3000  http://localhost:3000  up
{"id":1,"body":"hello from dev"}
```

Stop it with `reliant forge env down dev`. If `env up` fails, see [Troubleshooting](#troubleshooting).

**6. Set the secrets and deploy staging**

`secret set` reads the value from stdin and creates the hosted env on first use ([Secrets](https://docs.reliantlabs.io/hosting/secrets.md)). `--yes` approves the plan the deploy prints:

```bash terminal theme={null}
openssl rand -hex 16 | reliant forge env secret set --env staging SESSION_SECRET
reliant forge env deploy staging --yes
```

```text Output (trimmed) theme={null}
SESSION_SECRET: created v1 (32 bytes) in hosted env "staging" at https://admin.reliantapi.com
[deploy] cutting new release 20261120.073348-efe09493435b because no release in https://admin.reliantapi.com records this checkout's tree (efe09493435b)
  readiness: all 3 workload(s) ready
  url api: https://mint-albatross.reliantlabs.dev (served through the regional ingress, no CDN)
Rollout of 20261120.073348-efe09493435b to staging: SUCCEEDED
  api                      succeeded    1/1 updated
  migrate                  succeeded    0/0 updated
```

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:

```bash terminal theme={null}
curl -s -X POST -H 'Content-Type: application/json' -d '{"body":"hello from staging"}' https://<your-url>/notes
reliant forge obs workloads staging
```

```text Output theme={null}
{"id":1,"body":"hello from staging"}
3 workload(s) on staging: 0 need a look, 0 crash-looping, 0 restart(s), 0 failed job run(s)
```

`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](https://docs.reliantlabs.io/hosting/observability/forge-obs).

**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:

```bash terminal theme={null}
reliant forge env delete staging --yes
```

## 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](https://docs.reliantlabs.io/forge/deploy/releases-and-promotion.md) covers deploying from a pipeline.

## Troubleshooting

> [accordion] has a Dockerfile and no Go module: an app in another language
>
> 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.

> [accordion] container time="…" has no matching ownership labels
>
> 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>`.

> [accordion] container …-migrate-1 exited (0) … service did not become healthy
>
> `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.

> [accordion] exit code 7 from env deploy
>
> The deploy is queued on billing. Open the link it prints, set up billing, and deploy again.

## Next steps

> [card] [Send OpenTelemetry from any app](https://docs.reliantlabs.io/guides/observability/send-opentelemetry-from-any-app.md)
>
> Turn the INCONCLUSIVE verdict into real request, error and latency data.

> [card] [Deploy a Go API with managed Postgres](https://docs.reliantlabs.io/guides/hosting/deploy-go-api-managed-postgres.md)
>
> The same release flow for a Forge-built service.

> [card] [Managed Postgres](https://docs.reliantlabs.io/hosting/managed-postgres.md)
>
> What the managed database gives each env, and what it costs.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.