Deploying a generated service

Every generated backend can be deployed as one container image to AWS, GCP, Azure or any Kubernetes cluster. This page covers:

• the production image;
• its runtime contract (environment variables and probes);
• the broker for each cloud;
• the deployment code ghk generate writes when deploy is configured: Terraform for each cloud, and a Helm chart.

Production image

ghk generate writes a Dockerfile and a .dockerignore next to the backend. Each image:

• Builds in stages. It compiles in the same toolchain image the golden builds use, then copies only the result into a smaller runtime image.
• Runs without root. The user is UID 10001, or the image's own node, app or nonroot user.
• Takes configuration only from environment variables. Nothing environment-specific is baked into the image, so one image runs in dev, staging and prod.
• Has no HEALTHCHECK and no curl. The platform probes the HTTP paths below.

docker build -t orders-svc .
docker run -p 8080:8080 -e DATABASE_URL=... -e AMQP_URL=... -e JWT_SECRET=... orders-svc

Where readiness equals liveness, the stack does not yet check its dependencies in the probe.

Runtime contract

Keep secrets in the platform's secret manager (AWS Secrets Manager, GCP Secret Manager or Azure Key Vault) and inject them as environment variables. The generated Terraform does this for you. The agent firewall requires human approval for changes to Dockerfile and deploy/**.

Event broker per cloud

The adapter is chosen when the service starts: GHK_BROKER if set, otherwise the broker whose variables are present, otherwise stack.messaging. For every broker, the outbox relay marks a row as published only after the broker has accepted the message. A message that fails in the consumer goes to the dead-letter destination (<service>.dlx → <service>.dlq) and is not redelivered.

Deployment targets (deploy)

{
  "deploy": {
    "cloud": "gcp",
    "compute": "containers",
    "environments": ["dev", "staging", "prod"],
    "region": "us-central1"
  }
}

• cloud: aws, gcp or azure.
• compute:
  • containers (the default) is the managed container service, under deploy/terraform/<cloud>/;
  • kubernetes is a Helm chart under deploy/helm/<service>/;
  • both writes both;
  • vm runs the image on one virtual machine (below), for demos and small workloads.
• environments: one .tfvars, Terraform backend file and Helm values file per environment.

ghk generate writes deploy/README.md with the exact commands. Only backends with a production image get deployment targets.

• Secrets: DATABASE_URL, JWT_SECRET, the broker URL and the framework secrets (SECRET_KEY_BASE, APP_KEY, DJANGO_SECRET_KEY) are generated by Terraform and stored in the cloud's secret manager. They also live in the Terraform state, so keep the state backend encrypted and access-controlled.

• Separate outbox relay: Django, Laravel and Rails run their outbox relay as a separate process (manage.py outbox_relay, artisan outbox:relay, rails outbox:relay). It is deployed as a second ECS service, a Cloud Run worker pool, a Container App without ingress, or a Helm Deployment.

• Database TLS: the generated DATABASE_URL ends in ?sslmode=require: connections are encrypted, and, as in libpq, the managed database's certificate is not verified. db_require_tls (on by default) makes the database refuse unencrypted connections; turn it off only for a client that cannot use TLS. Use sslmode=verify-full&sslrootcert=<file> to verify the certificate against the cloud's CA bundle.

• The Helm chart covers:

  • a Deployment with startup, liveness and readiness probes and a restricted security context (non-root, no privilege escalation, all capabilities dropped, RuntimeDefault seccomp);
  • a Service, an HPA, a PodDisruptionBudget and an optional Ingress;
  • a ServiceAccount whose workload-identity annotation (eks.amazonaws.com/role-arn, iam.gke.io/gcp-service-account or azure.workload.identity/client-id) is set in values-<env>.yaml.

  Secrets come from an existing Kubernetes Secret, created from the cloud secret manager by External Secrets Operator or the Secrets Store CSI driver. They are never in values files.

One virtual machine (compute: "vm")

The database, broker and secret store are the same as for containers (the same Terraform files). Only the compute changes:

At boot, cloud-init installs Docker, reads each secret from the secret store with the machine's identity into /opt/app/app.env (mode 600; the values are never in the user data), and runs the image behind Caddy: with domain set, Caddy obtains a Let's Encrypt certificate for it (point the DNS record at the public_ip output); without it, the service answers plain HTTP on port 80. Stacks with a separate relay process also run it there. Only ports 80 and 443 are open, to allowed_cidrs.

Shared base stack for a monorepo (deploy.base, AWS)

By default every service owns its database instance and broker: nine services, nine RDS instances and nine brokers. With "base": { "dir": "../../infrastructure/base" } in deploy (the same directory in each service), ghk generate writes a base module at <dir>/aws for every service that points at it, and changes the service module:

Apply the base first, run its bootstrap SQL, then apply the services. Each service connects with its own role to its own database. Google Cloud and Azure report a configuration error for deploy.base in this version.

A new image changes the boot script, so each deployment replaces the machine: a few minutes without service. Use containers when that matters. There is no collector sidecar: set OTEL_EXPORTER_OTLP_ENDPOINT in extra_environment to export traces.

Telemetry

The runtime kernel traces every command, outbox publish and inbox delivery with OpenTelemetry. W3C traceparent flows from the HTTP request through the outbox to the consumer; IT7 checks this in every stack.

Export. When OTEL_EXPORTER_OTLP_ENDPOINT is set, the service exports its traces over OTLP/HTTP, batched, with service.name from OTEL_SERVICE_NAME. Each stack uses its official SDK:

Collector per cloud. The generated Terraform runs an OpenTelemetry collector as a sidecar and points the service at http://localhost:4318. Set enable_tracing = false to turn it off.

CI/CD (ci)

{ "ci": { "provider": "github" } }

The pipeline is written at the repository root, and only when ci.provider is set. With deploy and no ci, the provider defaults to GitHub Actions. The gherkin-ai version is pinned to the one that generated it.

The GitHub workflow header lists the repository variables each environment needs. For example, AWS needs AWS_ROLE_ARN, AWS_REGION and ECR_REPOSITORY; GCP needs GCP_WORKLOAD_IDENTITY_PROVIDER and the other GCP variables.

Context for AI agents

ghk generate and ghk implement write .ghe/deployment-context.md and .json. They contain the runtime contract (environment variables, port and probes), the deployment target and its secrets, the rules every change must follow, and a production checklist.

The rules:

• configuration only from the environment;
• no hardcoded hosts or secrets;
• keep the probes working;
• events only through the outbox;
• logs to stdout;
• handle SIGTERM;
• backward-compatible migrations.

The runtime kernel's tables are created by the service itself when it starts (every replica, serialized by an advisory lock), so the first deployment needs no migration step. With GHK_MIGRATE=false the service skips it: use that when the service's database user has no DDL rights and a migration job creates the tables (RUNTIME-KERNEL.md).

The implement prompt (compact with -C) and the domain and backend agent prompts include a Deployment Readiness section.

ghk validate checks deployment readiness:

• the Dockerfile exists, runs as non-root, and has no secret in ENV or ARG;
• .env.example documents the variables;
• deploy/ contains no hardcoded password or key.

The agent firewall requires human approval for Dockerfile, deploy/**, *.tf, *.tfvars, *.tfbackend and Helm charts.

Verification

For each backend, node scripts/golden-build.js <stack> takes these steps:

1. Builds the production image.
2. Starts it next to PostgreSQL, RabbitMQ and an OpenTelemetry collector.
3. Waits until both probes answer 200.
4. Sends one command with a JWT, expects 202, and requires the collector to receive the service's spans.
5. Removes everything.

Pass --no-image to skip this step.

The deployment code is verified without a cloud account:

CI never runs terraform apply.