> ## 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 a Go API with managed Postgres to Reliant hosting

> Ship a Forge Go API, its migrations and a managed Postgres to production as one release, then prove it healthy with forge obs check.

You will ship the `shop` app from [Build a Go and React app](https://docs.reliantlabs.io/guides/forge/build-go-react-app-connect-rpc.md) to production on [Reliant hosting](https://docs.reliantlabs.io/hosting/overview.md): the Go API, a migration job, a managed Postgres and the frontend, as one release. At the end the API answers on a public URL and `forge obs check` has judged it.

The environment declares the database, and the platform fills `DATABASE_URL` in each workload at deploy time, so you never handle a connection string. [Managed Postgres](https://docs.reliantlabs.io/hosting/managed-postgres.md) covers backups and restore.

## Before you begin

* The `shop` project from [Build a Go and React app](https://docs.reliantlabs.io/guides/forge/build-go-react-app-connect-rpc.md), with every change committed.
* Forge v1.6.1 or later in the project (`reliant forge --version`). This guide ran at `v1.6.1-0.20261115024114-0ab7c562e817`.
* Docker: the API image is built on your machine.
* Reliant, signed in, in an organization with [hosting billing](https://docs.reliantlabs.io/hosting/overview.md#billing).

**1. See what prod will run**

`forge project new` already declared a hosted `prod` environment in `deploy/kcl/prod/main.k`. List what it renders:

```bash terminal theme={null}
reliant forge env render prod --list
```

```text Output (trimmed) theme={null}
CLUSTER  KIND             NAMESPACE  NAME     APP
hosted   Workload         -          migrate  -
hosted   Workload         -          api      -
hosted   StaticSite       -          web      -
hosted   ManagedDatabase  -          shop     -
```

`migrate` runs `db migrate up` before the rollout, `api` is every service in one process, `web` is the static frontend and `shop` is the database. [What gets deployed](https://docs.reliantlabs.io/forge/deploy/what-gets-deployed.md) explains each.

**2. Cut a release**

A release builds every artifact once and records its digest, so every later deploy of it ships the same bytes:

```bash terminal theme={null}
reliant forge env build prod --release v0.2.0
```

```text Output (trimmed) theme={null}
[declare] env prod: persistent, 4 workload(s), 0 secret(s), 4 object(s) recorded at https://admin.reliantapi.com
[build]   hosted (built here):       migrate, api
[build]   Frontends (skip docker):   web
[build] Cut release v0.2.0 (2 image(s), 0 package(s), 0 file(s)): …/guides-sandbox-goapi, …/web/static.v1, web.sourcemaps
[build]   Deploy:  forge env deploy <env> v0.2.0
[build] All 2 builds succeeded.
```

`--plan` checks the cut without building. Use a version no other project in your organization has cut ([Troubleshooting](#troubleshooting)). [Releases and promotion](https://docs.reliantlabs.io/forge/deploy/releases-and-promotion.md) explains the model.

**3. Deploy it**

```bash terminal theme={null}
reliant forge env deploy prod v0.2.0 --yes
```

`--yes` approves the plan forge prints; `--plan-only` then `--approve <digest>` splits review from approval. The deploy waits for the rollout:

```text Output (trimmed) theme={null}
direction INITIAL  FIRST PROMOTE — this environment has never been bound to a release
  first publish  shop (database) — not on the control plane yet; this deploy creates it
  readiness: all 4 workload(s) ready
  url api: https://maple-tern.reliantlabs.dev (served through the regional ingress, no CDN)
  url web: https://tranquil-civet.sites.reliantlabs.dev (served through the CDN edge)
Rollout of v0.2.0 to prod: SUCCEEDED
  api                      succeeded    1/1 updated
  migrate                  succeeded    0/0 updated
  web                      succeeded    0/0 updated
  identity: ready
```

It took about five minutes. `identity: ready` is the environment's hosted sign-in instance.

**4. Check the database and the migration**

```bash terminal theme={null}
reliant forge obs workloads prod --all --jobs all
```

```text Output theme={null}
3 workload(s) on prod: 0 need a look, 0 crash-looping, 0 restart(s), 0 failed job run(s)

WORKLOAD    HEALTH   READY  RESTARTS  LAST EXIT  WHY
api         HEALTHY  1/1    0
migrate     HEALTHY  0/1    0
postgresql  HEALTHY  1      0
```

The migration job has no failed run. `db query` runs a read-only, audited query (it needs the `db:query` grant):

```bash terminal theme={null}
reliant forge db query prod "select count(*) from products" \
  --confirm-env prod --reason "check the migration ran"
```

```text Output theme={null}
count
0
(1 row, 5 ms; release v0.2.0; audit 9d4c2942-7cc2-45cc-9583-ba8dc7dcb80f)
```

The table exists and is empty: seeding is dev-only.

**5. Call the live API**

Use the `url api:` the deploy printed:

```bash terminal theme={null}
curl -s https://maple-tern.reliantlabs.dev/healthz
curl -s https://maple-tern.reliantlabs.dev/readyz
curl -s -X POST -H 'Content-Type: application/json' -d '{}' \
  https://maple-tern.reliantlabs.dev/services.catalog.v1.CatalogService/ListProducts
```

```text Output theme={null}
ok
{"status":"ready","checks":[{"name":"db","ok":true},{"name":"api_listener","ok":true}]}
{"code":"unauthenticated","message":"missing Authorization header (procedure is not on the unauthenticated allow-list)"}
```

`readyz` reports the database connection, and the RPC refuses an unsigned caller because authentication is fail-closed. `reliant forge env status prod` confirms the running images match the release (`3 match, 0 drifted`).

**6. Prove the release with obs check**

Send the API some traffic, then judge the promotion:

```bash terminal theme={null}
reliant forge obs check prod --wait --json
```

It waits for the 15-minute window after the promotion to close. Then branch on `exit_code`:

| Exit | Verdict | What to do |
| - | - | - |
| 0 | PASS | Done. |
| 1 | FAIL | Run the commands in `suggested[]`, fix, cut a new release, deploy it, check again. |
| 2 | INCONCLUSIVE, or could not look | Report "not proven good". `reason_code` says why. |
| 8 | `--wait` ran out | Check again later. |

This first deploy returned exit 2 after 476 requests with no errors:

```text Output (trimmed) theme={null}
"exit_code": 2,
"verdict": "INCONCLUSIVE",
"reason_code": "thin_baseline",
"reason": "the before window is too thin to compare against: api had 0 requests before the promotion (476 after), below min_requests (50), …"
```

The check compares the window after a promotion with the one before, and a new environment has no before, so this verdict is final. To judge the after window alone, drop the baseline requirement for one call:

```bash terminal theme={null}
reliant forge obs check prod --threshold require_baseline=none --json
```

That returned `"verdict": "PASS"`, exit 0: no errors, new issues, alerts or restarts after the release. It cannot say "no worse than before"; your next release has a baseline. See [`forge obs`](https://docs.reliantlabs.io/hosting/observability/forge-obs#the-exit-codes).

**7. Clean up**

If this was a trial, delete the environment. Its database and data go with it, irreversibly, unless you pass `--keep-data`:

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

```text Output (trimmed) theme={null}
Removed: the environment, its deployments, workloads, URLs, Flux objects, custom resources, namespaces
  AND its managed databases' data. IRREVERSIBLE (pass --keep-data to retain the databases).
Kept: the project's release images in the registry (they belong to the project, not this environment).
Deleted env prod; the platform is tearing it down, its databases included.
```

A minute later `curl https://maple-tern.reliantlabs.dev/healthz` returned `404 Not found`. The hosted project and its release images stay; no command deletes them.

## What this does not do

* It does not roll back. You recover by deploying an earlier release, and migrations run before every rollout, so keep them backward-compatible: [Safe migrations](https://docs.reliantlabs.io/deep-dives/safe-migrations.md).
* It does not autoscale. The API runs one replica.
* It does not decide who may call what. Access checks are handler code you write.
* Backups need the platform's backup storage to be ready: [Managed Postgres](https://docs.reliantlabs.io/hosting/managed-postgres.md#backups-and-point-in-time-restore).

## Troubleshooting

> [accordion] CutRelease failed (HTTP 404, not\_found) … release, environment or deployment not found
>
> Another project in your organization already cut this version: the images were pushed, but no release was recorded. This guide hit it with `v0.1.0`. Cut a version no other project has used.

> [accordion] the release does not cover everything prod declares … Missing from the ledger
>
> You renamed the project in `forge.yaml`, so the image is built under the new name while the workloads declare the old one. Set the last part of `image = "REPLACE-ME-REGISTRY.invalid/<name>"` in `deploy/kcl/workloads.k` and each `deploy/kcl/<env>/main.k` to the new name, commit, and cut again.

> [accordion] exit 7: the deploy is queued
>
> The organization has no hosting billing. The deploy is recorded and waits; forge prints the billing URL, and once billing is active it goes live by itself, with nothing to re-run. Not reproduced here (this organization has billing). See [Queued deploys](https://docs.reliantlabs.io/hosting/overview.md#queued-deploys).

> [accordion] exit 5: plan\_unconfirmed
>
> No terminal to ask on and no `--yes`, or a dirty checkout: nothing was promoted. Commit, then re-run with `--yes`.

## Next steps

> [card] [Promote staging to production](https://docs.reliantlabs.io/guides/hosting/promote-release-staging-to-production.md)
>
> Deploy the same release to staging first, then promote it by digest.

> [card] [Gate prod on release health](https://docs.reliantlabs.io/guides/hosting/gate-production-deploy-release-health.md)
>
> Refuse a production promotion until staging's check passes.

> [card] [Managed Postgres](https://docs.reliantlabs.io/hosting/managed-postgres.md)
>
> Backups, point-in-time restore and keeping data when you delete an environment.

> [card] [Releases and promotion](https://docs.reliantlabs.io/forge/deploy/releases-and-promotion.md)
>
> Plans, approvals, compare-and-set promotions and rollback floors.


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