Coder on Google Cloud Run

Coder is an open-source, self-hosted platform for provisioning remote development environments (workspaces) defined as code with Terraform — developers get consistent, ready-to-code environments while platform teams keep source and dependencies on their own infrastructure. This module deploys the Coder control plane on Cloud Run v2 on top of the App_CloudRun foundation, which provisions and manages the shared Google Cloud infrastructure.

This guide focuses on the cloud services Coder uses and how to explore and operate them from the Google Cloud Console and the command line. For the mechanics common to every Cloud Run application — service identity, ingress and load balancing, scaling and concurrency, CI/CD, Cloud Armor, IAP, Binary Authorization, VPC Service Controls, backups, and the deployment lifecycle — refer to the App_CloudRun foundation guide rather than repeating them here.

1. Overview

Coder runs as a single Go binary (coder server) in a container on Cloud Run v2. The deployment wires together a focused set of Google Cloud services:

Capability	Google Cloud service	Notes
Compute	Cloud Run v2	Go control-plane service, 2 vCPU / 4 GiB by default, always-allocated CPU
Database	Cloud SQL for PostgreSQL 15	Required — Coder needs PostgreSQL 13+; MySQL is rejected at plan time
Object storage	Cloud Storage	A `storage` bucket provisioned automatically (available for operator use)
Image build	Cloud Build + Artifact Registry	Thin custom wrapper built FROM `ghcr.io/coder/coder`
Secrets	Secret Manager	Database password managed automatically — Coder needs no app secret of its own
Ingress	Cloud Run URL / Cloud Load Balancing	Default `run.app` URL, optional external HTTPS load balancer + custom domain

Sensible defaults worth knowing up front:

PostgreSQL 15 is mandatory. Coder requires PostgreSQL 13+; a plan-time validation rejects MySQL engines.
The control plane is stateless. All state — templates, workspaces, users, sessions, the build queue, and Coder's self-generated signing keys — lives in PostgreSQL. No NFS, no Redis, no Common-managed application secret.
cpu_always_allocated = true and min_instance_count = 1. coder server runs built-in provisioner daemons in-process that continuously poll the database for pending workspace builds and terminate workspace agent connections — this background work stalls under request-based CPU throttling or scale-to-zero.
The connection URL is assembled at runtime. The custom entrypoint builds CODER_PG_CONNECTION_URL (a postgres:// URL with a URL-encoded password) from the Foundation-injected DB_* variables, preferring the private-IP TCP path with sslmode=require on Cloud Run.
CODER_ACCESS_URL is set automatically from the injected Cloud Run service URL, so workspace/agent connection URLs and OAuth redirect URIs are correct out of the box.
A db-init job runs on every apply to idempotently create the Coder database and role; Coder runs its own schema migrations on server boot.
Health probes target /healthz (unauthenticated) with a 60-second initial delay for first-boot schema migration.
The database password is generated automatically and stored in Secret Manager.
application_version = "latest" maps to a pinned tag (v2.24.1) via the app-specific CODER_VERSION build ARG — Coder's GHCR tags are semver-prefixed.

This module deploys the Coder control plane. Provisioning actual workspaces additionally requires a configured provisioner and a compute target (e.g. a Kubernetes cluster or a cloud VM template), set up post-deploy through Coder's template system.

2. Google Cloud Services & How to Explore Them

All commands assume PROJECT and REGION are set. Service and resource names are reported in the deployment Outputs.

A. Cloud Run — the Coder service

Coder runs as a Cloud Run v2 service with always-allocated CPU and a warm minimum instance, so the in-process provisioner daemons keep polling for workspace builds even with no inbound requests. Each deployment creates an immutable revision; traffic can be split across revisions for safe rollouts.

Console: Cloud Run → select the service for revisions, traffic, logs, and metrics.

CLI:

gcloud run services list --project "$PROJECT" --region "$REGION"
gcloud run services describe <service-name> --project "$PROJECT" --region "$REGION"
gcloud run revisions list --service <service-name> --project "$PROJECT" --region "$REGION"

See App_CloudRun for scaling, concurrency, execution environment, and traffic splitting.

B. Cloud SQL for PostgreSQL 15

Coder stores everything — users, organizations, templates, workspace state, provisioner job queue, and its signing keys — in a managed Cloud SQL for PostgreSQL 15 instance. The service connects over private IP with sslmode=require (Coder's URL-form DSN cannot carry the Unix-socket path); the db-init Job creates the application database and role on first deploy.

Console: SQL → select the instance for connections, backups, flags, metrics.

CLI:

gcloud sql instances list --project "$PROJECT"
gcloud sql instances describe <instance-name> --project "$PROJECT"
gcloud sql connect <instance-name> --user=<db-user> --project "$PROJECT"

The instance name, database, user, and password secret are in the Outputs. See App_CloudRun for the connection model, backups, and password rotation.

C. Cloud Storage

A dedicated Cloud Storage bucket (suffix storage) is provisioned automatically. Coder does not require it for control-plane operation — the control plane keeps no files on disk — but it is available for template assets or operator use.

Console: Cloud Storage → Buckets.

CLI:

gcloud storage buckets list --project "$PROJECT"
gcloud storage ls gs://<storage-bucket>/        # bucket name is in the Outputs

D. Cloud Build & Artifact Registry

container_image_source = "custom" triggers a Cloud Build that wraps ghcr.io/coder/coder:<version> with the cloud entrypoint and pushes the result to Artifact Registry (the base image is mirrored first, enable_image_mirroring = true).

Console: Cloud Build → History; Artifact Registry → Repositories.

CLI:

gcloud builds list --project "$PROJECT" --limit 5
gcloud artifacts docker images list <region>-docker.pkg.dev/$PROJECT/<repo> --limit 5

E. Secret Manager

The database password is the only secret in the deployment — stored in Secret Manager and injected at runtime as DB_PASSWORD, then URL-encoded into the connection URL by the entrypoint. Coder self-generates its signing keys and persists them in PostgreSQL, so no session/app secret exists to manage.

Console: Security → Secret Manager.

CLI:

gcloud secrets list --project "$PROJECT"
gcloud secrets versions access latest --secret=<secret-name> --project "$PROJECT"

See App_CloudRun for injection and rotation details.

F. Networking & ingress

The service is reachable at its run.app URL by default; the entrypoint exports that URL as CODER_ACCESS_URL, from which Coder builds workspace and agent connection URLs. An external HTTPS load balancer with a custom domain, Cloud CDN, and Cloud Armor can be layered on; ingress settings and VPC egress control connectivity.

Console: Cloud Run (service URL); Network services → Load balancing.

CLI:

gcloud run services describe <service-name> --region "$REGION" --format='value(status.url)'
gcloud compute addresses list --project "$PROJECT"

See App_CloudRun.

G. Cloud Logging & Monitoring

Container logs (structured, to STDOUT) flow to Cloud Logging; Cloud Run and Cloud SQL metrics flow to Cloud Monitoring, with optional uptime checks and alert policies.

Console: Logging → Logs Explorer; Monitoring → Dashboards / Alerting.

CLI:

gcloud run services logs read <service-name> --project "$PROJECT" --region "$REGION" --limit 50

3. Coder Application Behaviour

First-deploy database setup. A db-init Job (postgres:15-alpine) connects as the postgres superuser and idempotently creates the Coder role (LOGIN CREATEDB), creates the database, grants all privileges, and reassigns ownership of schema public to the app role (Coder's migrations create all objects there). The job runs on every apply and is safe to re-run.
Migrations run on boot. Coder applies its own schema migrations every time coder server starts — version upgrades need no manual migrate step. First boot against a fresh database takes longer; the startup probe allows up to ~8 minutes before giving up.
Runtime DSN assembly. The cloud entrypoint builds CODER_PG_CONNECTION_URL from DB_HOST/DB_IP/DB_USER/DB_PASSWORD/DB_NAME: on Cloud Run it prefers the private IP with sslmode=require (the Cloud SQL socket path cannot live in a URL authority); the password is percent-encoded so special characters never break the URL. An explicitly provided CODER_PG_CONNECTION_URL wins.
Access URL. CODER_ACCESS_URL is set from the injected CLOUDRUN_SERVICE_URL. Coder builds workspace/agent connection URLs and OAuth redirect URIs from it — if you front the service with a custom domain, set CODER_ACCESS_URL in environment_variables to that domain.
No app secrets. Coder generates and persists its signing keys in PostgreSQL. Container recreation, scaling, and redeploys are safe; nothing desyncs.
First-run setup. The first visit to the service URL prompts you to create the initial admin (owner) account — complete it promptly, as the endpoint is publicly reachable until then (ingress_settings = "all" by default).
Workspace provisioning is a day-2 step. The control plane alone runs no workspaces. Create a template (Terraform) pointing at a compute target — e.g. a GKE cluster or GCE VMs — and ensure the provisioner has credentials for it.
Health path. Startup, liveness, and readiness probes target /healthz, which Coder serves unauthenticated with HTTP 200 once the server is up.

Verification:

SERVICE_URL=$(gcloud run services describe <service-name> --region "$REGION" --format='value(status.url)')
curl -s -o /dev/null -w "%{http_code}\n" "$SERVICE_URL/healthz"     # expect 200
curl -s "$SERVICE_URL/api/v2/buildinfo"                             # Coder version info

4. Configuration Variables

Variables are grouped exactly as they appear on the deployment platform. Only settings specific to or notable for Coder are listed; every other input is inherited from App_CloudRun with its standard behaviour.