# Deploying on Cloud Run

How to run `my` on Google Cloud with the OpenTofu module [`mycroblog-gcp`](https://github.com/mycroblog/my/blob/main/deploy/opentofu/README.md): Cloud Run, Cloud Tasks, Cloud Scheduler, Cloud Storage, and Pub/Sub, with a PostgreSQL database on Neon, behind a global external Application Load Balancer. The service runs no instance while nobody uses it, except for a tick that wakes the server each minute. A server costs money: expect about $37 a month before storage, traffic, and open streams, and read [Costs](#costs) for what care can reduce.

The module needs OpenTofu 1.11 or later. Terraform is not supported.

## What it creates

One block of `mycroblog-gcp` creates all of this. Each row is a section of the module, and its default is what this guide deploys; [the module's README](https://github.com/mycroblog/my/blob/main/deploy/opentofu/README.md#sections) lists the other kinds.

| Part | Section | Resources |
| --- | --- | --- |
| Server | `service`, `jobs` | A Cloud Run service with `role = all`, a migration job, a console job while you need it, a service account, and public access |
| Traffic | `ingress` | A global external Application Load Balancer with a certificate. A domain mapping or Cloudflare are the other kinds, and a media host on Cloudflare can sit beside any |
| Jobs | `queue` | A Cloud Tasks queue, a Cloud Scheduler job, and a service account that calls the server |
| Media | `media` | A private bucket |
| Real-time updates | `stream` | A topic and a custom role. The server creates and removes its own subscriptions |
| Database | `database` | A secret for its URL: you create the database by hand |
| Email | `mail` | A secret for the SMTP password: any SMTP service |
| Secrets | | A generated VAPID key, and the secrets that only you can fill, empty |
| KEK | `kek` | A generated secret mounted as a file. Cloud KMS is the other kind |
| Metrics, traces, errors | `observability` | The APIs of Cloud Monitoring, Cloud Trace, and Error Reporting, which read what Cloud Run sends them |

Secret values never reach the OpenTofu plan or state: you add the ones that come from elsewhere yourself, and the module generates the KEK and the VAPID key through write-only attributes.

## Before you start

- `tofu` 1.11 or later, `gcloud`, and `jq`, where you apply: an apply that changes the version runs the migration from there, through `gcloud`.
- A Google Cloud project with billing, used for this instance alone, and an account on it with the Owner role.
- A domain for [`host`](https://mycroblog.dev/next/reference/configuration/#host). It cannot change later: read [Settings you cannot change later](https://mycroblog.dev/next/operations/production-checklist/#settings-you-cannot-change-later).
- A version of `my` from the [releases](https://mycroblog.dev/next/operations/running/#get-the-image). There is no `latest` tag.

## First deployment

### 1. Enable the APIs

```sh
gcloud services enable --project="$PROJECT" run.googleapis.com cloudtasks.googleapis.com cloudscheduler.googleapis.com \
  pubsub.googleapis.com secretmanager.googleapis.com storage.googleapis.com iam.googleapis.com \
  iamcredentials.googleapis.com cloudresourcemanager.googleapis.com logging.googleapis.com compute.googleapis.com \
  monitoring.googleapis.com
```

`compute.googleapis.com` is for the load balancer.

### 2. Create the database on Neon

Expect the Launch plan: with the default tick, the compute never stops. The Free plan works too, with the trade-offs under [Costs](#costs).

In the Neon console, create a project in a region near your Cloud Run region, and copy its connection strings. The module never creates it, so its password stays out of the OpenTofu state. A project has two connection strings, and the deployment uses each where it belongs:

- The **direct** one (the host without `-pooler`) is required. The migration job and the console always use it: `my schema apply` holds a session-level lock, which a pooler in transaction mode does not keep.
- The **pooled** one (the host with `-pooler`) is optional, for the service. Neon's pooler handles what the server needs: see [Through a connection pooler](https://mycroblog.dev/next/operations/database/#through-a-connection-pooler). Set `database = { pooled = true }`, and the module creates a second secret for it.

Without a pooled string, the service uses the direct one too, at the database's connection limit, which `service.max_instances` bounds. To raise the pool from its default of 4 per instance, for the 80 requests a Cloud Run instance takes at once, add `pool_max_conns` to the string the service uses, for example `postgres://...-pooler...neon.tech/neondb?sslmode=require&pool_max_conns=8`. See [Waiting for a database connection](https://mycroblog.dev/next/operations/running/#waiting-for-a-database-connection).

### 3. Copy the example and set the variables

Start from a copy in an empty directory, with the provider lock file, from the release you deploy:

```sh
VERSION=v0.1.0
git clone --depth 1 --branch "$VERSION" https://github.com/mycroblog/my.git my-source
mkdir my-deployment
cp -r my-source/deploy/opentofu/examples/gcp-cloud-run-neon/. my-deployment/
rm -rf my-source
cd my-deployment
cp terraform.tfvars.example terraform.tfvars
```

`main.tf` is the `google` provider and one block, `module "mycroblog"`. **Set `ref` to that release.** The block names a release with `?ref=`, which a stable release's copy already has right. The server image is the same release, so `ref` alone names what runs. For a prerelease, set both yourself: `sed -i "s/?ref=[^&]*/?ref=$VERSION/" main.tf`, and `image = { version = "0.1.0-rc.4" }` in the block, the version without its `v`, since the module of a prerelease does not default to its own image. The module exists only from the first release that contains it, so an earlier tag has no example to copy. Keep this directory: it holds your state and your settings.

Fill in `terraform.tfvars`. `mail_from`, `mail_smtp_host`, and `mail_smtp_username` configure [email](https://mycroblog.dev/next/operations/email/); the port is 587, since Google Cloud blocks outbound port 25. To change anything else, add the section to the block in `main.tf`, such as `ingress = { kind = "domain-mapping" }`: every section and what it refuses is in [the module's README](https://github.com/mycroblog/my/blob/main/deploy/opentofu/README.md#sections).

`settings` takes any other setting from the [configuration reference](https://mycroblog.dev/next/reference/configuration/) by its key, and `secrets` the keys of secret settings, each of which gets an empty secret to fill. A key that a section or the module sets fails the plan, and so does a key the module does not take on Cloud Run, such as `listen`; the error says why. Decide on [`account_domain`](https://mycroblog.dev/next/reference/configuration/#account_domain) now, as `settings = { account_domain = "example.org" }`, if handles use another domain.

**The state** stays in this directory by default. It holds no secret values, but it is the only record of what was created: keep it in a bucket with a `backend "gcs"` block if more than one person runs this.

### 4. Create the secrets and add their values

This creates the secrets, and generates the KEK and the VAPID key:

```sh
tofu init
tofu apply -target=module.mycroblog.module.secrets -target=module.mycroblog.module.kek_secret_manager
```

`tofu init` also fetches the scripts of that release: `migrate.sh`, which an apply runs, and `console.sh`, which a later step uses:

```sh
SCRIPTS=.terraform/modules/mycroblog/deploy/opentofu
```

**Copy the KEK now**, and keep the copy apart from the database, for example in a password manager. Without it a [backup](https://mycroblog.dev/next/operations/backup/) cannot be restored, and the accounts' keys are lost. `tofu output kek` has the command. Do the same with the VAPID key, whose loss ends every Web Push subscription:

```sh
gcloud secrets versions access latest --secret=my-kek --project="$PROJECT"
gcloud secrets versions access latest --secret=my-vapid-key --project="$PROJECT"
```

Then add the values that come from elsewhere. `tofu output secrets_to_fill` lists each secret the module created empty, with what goes in it and the command that adds it. An instance whose secret cannot be read does not start, so add them before the service:

```sh
printf '%s' 'postgres://...' | gcloud secrets versions add my-database-url --project="$PROJECT" --data-file=- # the direct string
printf '%s' '<the SMTP password>' | gcloud secrets versions add my-smtp-password --project="$PROJECT" --data-file=-
```

The KEK reaches the server as a mounted file, named by `MY_KEK_FILE`. The others are environment variables resolved when an instance starts, so a new version takes effect on the next instance: deploy a new revision to make sure.

**OpenTofu generates the KEK once and never again.** The secret and its version have `prevent_destroy`, and the version number that would write a new value is fixed in the module: a new random KEK makes everything the old one encrypted unreadable. To rotate, follow [Rotate the KEK](https://mycroblog.dev/next/operations/key-management/#rotate-the-kek), adding the new value with `gcloud secrets versions add`. OpenTofu does not track what you add there.

To keep the KEK in Cloud KMS from the start, set `kek = { kind = "kms" }` before this step, target `module.mycroblog.module.kek_kms` in place of `kek_secret_manager`, and enable `cloudkms.googleapis.com`.

### 5. Apply

```sh
tofu apply
```

This creates everything else, in an order that the service's startup probe needs: the probe waits for `/health/ready`, which answers `503` until the schema exists. The migration job comes first, with what it depends on, which includes the load balancer's address, since the server's settings name it. Then the apply runs `my upgrade` as an execution of the job, from your machine through `gcloud`, and waits for it: `my config check`, `my db upgrade -check`, `my schema apply`, and `my db upgrade`, which stops at the first that fails. Its output appears in the apply's. The first command that uses the database records `host` and `account_domain` in it. Only then does the apply create the services.

If the migration fails, the apply stops before the services. Fix the cause, often a secret without a value, and run `tofu apply` again: it runs the migration again.

### 6. Point the domain at the load balancer

`tofu output dns_records` lists one `A` record, of `host` to the load balancer's address. Add it at your DNS provider. If that provider has a proxy of its own, leave it off for this record.

The certificate is Google-managed and becomes active only once DNS points at the address, which can take a while. Until then `https://{host}` fails with a TLS error, so federation and browsers cannot reach the server yet. Nothing else waits for it: Cloud Tasks and Cloud Scheduler call the service's default `run.app` URL, `https://<service>-<project number>.<region>.run.app`. **Do not disable the default URL**, or jobs stop. That URL refuses requests from the internet, and Cloud Run counts these two as internal only from the same project and on that URL, not on a custom domain.

See [How traffic reaches the service](#how-traffic-reaches-the-service) for what else you can choose.

### 7. Create the first administrator

Cloud Run jobs have no terminal and no standard input, so `my admin create` prints a link that sets the password instead of reading one. Turn the [console](#the-console) on, and run:

```sh
tofu apply -var console_enabled=true
tofu output -json console | "$SCRIPTS/console.sh" admin create -username alice -email alice@example.com -password-link
tofu apply -var console_enabled=false
```

Open the link right away and set the password. It works once, for one hour. **It stays in Cloud Logging until then**, where anyone who can read the project's logs can use it. If it expires, run `my admin account password-reset-link @alice` through the console. Then turn on two-factor authentication.

### 8. Go through the checklist

Go through the [production checklist](https://mycroblog.dev/next/operations/production-checklist/), starting with [email](https://mycroblog.dev/next/operations/production-checklist/#email): SPF, DKIM, and DMARC on the domain of `mail_from`.

## The console

The console runs one `my` command with the image, settings, and secrets of the service. It exists only while `console_enabled` is on, so turn it off when you finish:

```sh
tofu apply -var console_enabled=true
tofu output -json console | "$SCRIPTS/console.sh" instance set registration_mode open
tofu apply -var console_enabled=false
```

`console.sh` waits for the command, prints its output and exit code, and exits with that code. It needs `roles/logging.viewer`, because a job's output goes to Cloud Logging. It uses the image the service runs: after an upgrade that stopped at the migration, that is the previous release, which the database still fits.

The command has no standard input and no terminal, so a command that reads a password or a file from them cannot run this way. What it prints stays in the logs, so do not run a command whose output you would not write there.

## Upgrading

Read [Upgrading](https://mycroblog.dev/next/operations/database/#upgrading) and the release notes first, and go one minor version at a time. An upgrade is an apply of the new release: the plan shows every service and job taking its image, and the apply runs the migration before any of them serves it.

```sh
# 1. Back up the database while nothing writes: see "The maintenance mode" below, and Backup and restore.
pg_dump --format=custom --file=my-before-upgrade.dump "$DATABASE_URL"

# 2. Name the new release in main.tf, as ?ref=v0.2.0, and fetch it.
tofu init

# 3. Read the plan, then apply it.
tofu plan
tofu apply
```

The image is the release that `ref` names, so changing `ref` is the whole upgrade. Read the plan before you apply it: a new release's module may change resources too. The apply does this, and stops at the first step that fails:

1. Gives the migration and console jobs the new image, with the rest of the plan that the services do not depend on.
2. Runs `my upgrade` as an execution of the migration job, from where you apply, and waits for it: `my config check`, `my db upgrade -check`, `my schema apply`, and `my db upgrade`. Its output appears in the apply's.
3. Deploys the new revision of each worker, then of the service. A revision takes traffic only when its startup probe passes on `/health/ready`.

**Where you apply** needs `gcloud` and `jq`, and credentials that may execute the job and read its logs (`roles/run.developer` and `roles/logging.viewer`, which Owner includes). The same holds for a CI job that applies.

**When a step fails**, the services stay on their revisions, and the release notes or the migration's output say why. Fix the cause and run `tofu apply` again, with the same version: it runs the migration again, and the steps that completed find nothing left to do. An apply that was interrupted, or that lost its connection, leaves the execution running on Cloud Run; the next apply waits for it to end before it starts its own. To go back after the schema changed, restore the backup: see [Rolling back](https://mycroblog.dev/next/operations/database/#rolling-back). An apply with an earlier version stops at the migration, since that release refuses a newer schema, and changes no service.

To try a release candidate, or to keep the image of an earlier release under a newer module, set the version yourself; it is the image tag, without the `v` of the release:

```hcl
  image = { version = "0.2.0-rc.1" }
```

### Checking the SQL first

The plan does not show the SQL of the migration. To read it before the apply, give the migration job the new image alone, and run `my upgrade -dry-run` in it, which changes nothing:

```sh
tofu apply -target='module.mycroblog.module.app.google_cloud_run_v2_job.one_off["migrate"]'
gcloud run jobs execute my-migrate --project="$PROJECT" --region=asia-northeast1 --args=upgrade,-dry-run --wait
gcloud logging read 'resource.type="cloud_run_job" AND resource.labels.job_name="my-migrate"' --project="$PROJECT" \
  --freshness=1h --format='value(textPayload)' --order=asc
```

### Destructive changes

When the release notes call for `-allow-destructive`, name that version in the block:

```hcl
  upgrade = { allow_destructive_for = "0.3.0" }
```

`my upgrade` gets `-allow-destructive` only on the apply of that version, so a value left in place lets no later release drop data.

### Pinning the image by digest

The [production checklist](https://mycroblog.dev/next/operations/production-checklist/#operations) recommends a digest, from the release notes:

```hcl
  image = { digest = "sha256:..." }
```

A digest names one image, whatever the tag beside it says, so change it in the same edit as `ref`: a digest left from the previous release keeps that release's image under the new version.

### The maintenance mode

The [maintenance mode](https://mycroblog.dev/next/operations/maintenance/) takes three applies, since the services change before the upgrade and after it. Add it to the settings of the block and apply, take the backup, raise `ref` and apply, then remove it and apply:

```hcl
  settings = { maintenance = "true" }
```

Without it, the old revision keeps serving during the migration, which [is not guaranteed to work](https://mycroblog.dev/next/operations/database/#the-server-during-an-upgrade). Settings changed by hand with `gcloud` do not last: the next apply puts back what the block says.

## Monitoring and alerts

The module adds an uptime check of `/health/live`, log-based metrics, and alert policies with the names of [the runbook](https://mycroblog.dev/next/operations/alerts/), which notify the addresses of `monitoring.notification_emails` (`alert_emails` in the example) or the channels of `notification_channels`. The input has no default: name who is notified, or set `monitoring = null` to leave all of it out. It has never been applied, so try it once by making a check fail. Each run of the check wakes an instance, which adds to [the tick's trade-off](#costs): `uptime_period`, 15 minutes by default, is how often.

## Changing a backend

Change the `kind` of its section. Each kind sets what it needs on the server, and the plan says what changes. Changing the database also means moving its data, since a new one is empty: take a [backup](https://mycroblog.dev/next/operations/backup/) of the old one and restore it into the new one while nothing writes. For example, Cloud SQL in place of Neon:

```hcl
  database = { kind = "cloud-sql" }
```

For a store outside Google Cloud, set `media.kind` to `s3`, for any S3-compatible service with its `endpoint`, or to `r2`, with `cloudflare.account_id`. Both read an access key from the secrets that `secrets_to_fill` lists.

## When you need a network

This guide needs none: Neon, Cloud Tasks, Cloud Storage, and Pub/Sub are all reached over the internet with the service's own identity, so Cloud Run attaches to nothing and there is nothing to pay for or look after.

You need one to put Memorystore in the deployment, since it has only private addresses, or to give Cloud SQL a private address in place of its public one. `network = { kind = "vpc" }` creates one, and `network = { kind = "existing", ... }` attaches to a VPC you have, which you describe by `network`, `subnetwork`, `private_services_range`, and `memorystore_connection_policy`:

```hcl
  network = { kind = "vpc" }
  kv      = { kind = "memorystore" }
```

Only private ranges go through the network, so the service reaches the internet as it did, with no Cloud NAT. `nat = true` sends everything through Cloud NAT instead, for a static source address. Enable the Service Networking and Network Connectivity APIs first, and the Compute Engine API. A network adds to the cold start of an instance, and Memorystore bills while the server is idle.

## Splitting jobs into workers

When one kind of job holds up the rest, give it its own service. Decide what to split from the metrics, as [Splitting workers by job type](https://mycroblog.dev/next/operations/running/#splitting-workers-by-job-type) says. One value, `workers`, goes to the service, the queue, and the monitoring, and every queue, URL, route, and setting comes from its keys, so you write none of them:

```hcl
  workers = {
    delivery = {
      job_types     = ["federation.fanout", "federation.deliver"]
      max_instances = 20
      concurrency   = 16
    }
  }
```

The plan refuses a split of the types that must stay together. It also needs a broker that reaches every process, which `stream.kind = pubsub` is.

The two common layouts of that page look like this. To keep deliveries from delaying the rest, use the value above. To keep email and notifications quick:

```hcl
  workers = {
    notify = {
      job_types = [
        "identity.verification_email", "identity.password_reset_email", "identity.password_notice_email",
        "identity.closure_email", "identity.deactivation_email",
        "notification.email", "notification.moderator_email", "notification.supporter_email",
        "notification.push", "notification.post_subscribers",
        "instance.notify_announcement", "voice.notify_started",
      ]
      max_instances = 10
    }
  }
```

Leave out the types of settings you have not set, as that page says: a type the server has not registered stops the start, and the plan cannot see which those are. With `workers`, the default service does not help with these types when it is free, since their tasks go to their own queue.

Each worker takes `job_types`, and `min_instances`, `max_instances`, `cpu`, `memory_mib`, `concurrency`, `max_concurrent_dispatches`, and `max_dispatches_per_second`, each the service's or the queue's where it is not named. A worker's service takes no traffic from outside. An upgrade moves each after the migration and before the default service, and with nothing to tell it: only a step that fails stops it. Each worker can bring what the service costs, and the connections of its instances count against the database's limit.

## How traffic reaches the service

`ingress.kind` decides this. The default is the load balancer, which is meant for production. The domain mapping is for trying a deployment cheaply: set `ingress = { kind = "domain-mapping" }`.

| | `load-balancer` (the default) | `domain-mapping` |
| --- | --- | --- |
| Monthly fee | About $18 for the forwarding rules, plus a charge per GB. Check the [pricing page](https://cloud.google.com/vpc/network-pricing): this figure could not be confirmed there | None |
| Status | Google Cloud's recommended way | A Preview feature that Google Cloud does not recommend for production, because of latency |
| Regions | Any | `asia-northeast1`, `us-central1`, and a few others |
| DNS | An `A` record, from `tofu output dns_records` | The records that the same output lists |
| Certificate | Google-managed, active once DNS points at the address | Google-managed, up to 24 hours |
| Domain ownership | Nothing beyond DNS | You, and every other account that applies, must be a [verified owner](https://cloud.google.com/run/docs/mapping-custom-domains) before you apply |
| `run.app` URL | Refused from the internet, so nobody goes around the load balancer | Reachable by anyone: a domain mapping cannot add a header, so the origin stays open |
| `MY_TRUSTED_PROXIES` | `169.254.0.0/16` and the load balancer's address | `169.254.0.0/16` |

Cloud Tasks and Cloud Scheduler arrive through neither: they call the default `run.app` URL directly.

### Cloudflare

`ingress = { kind = "cloudflare" }` puts Cloudflare in front of `host`, with the cache bypassed for everything, and `ingress.media_host` adds a cached media host beside any kind. Both need `cloudflare = { zone_id = "..." }`, and the token goes in `CLOUDFLARE_API_TOKEN`. They have run only on mocked providers.

- **Your plan decides the origin.** Cloud Run routes by `Host`, and Cloudflare offers the Host header override on the Enterprise plan only. On any other plan the origin must accept your host itself, so the module creates a domain mapping of each host, with the trade-offs of the table above, and Cloudflare connects to it. Whether its certificate is issued and renewed behind the proxy is unverified, so start with `cloudflare.proxied = false`. On the Enterprise plan, `cloudflare.host_header_override = true` connects to the `run.app` URL instead, with no domain mapping.
- **A header closes the origin.** The module adds a request header transform rule, and the server refuses a request without the header with a `403`, apart from health checks and the jobs' own `POST`s, which check their tokens. So nobody goes around Cloudflare through the `run.app` URL, and a caller's own Cloudflare Worker cannot choose the client address the rate limits see.
- **The value lands in the state.** The module generates it and writes it to the secret `my-origin-secret`, but the Cloudflare provider has no write-only form of a rule's header value, so keep the state private. [The CDN guide](https://mycroblog.dev/next/operations/cdn/#rotate-the-value) has how rotation works.
- **Nothing adds the header while a record is not proxied**, so the server refuses everything but its health checks: with `proxied = false` for a domain mapping's certificate, turn the proxy on once the certificate is active.
- **Turn off Bot Fight Mode** in the dashboard. It covers the whole zone and no rule can skip it, and a challenge on `/ap/`, `/.well-known/`, or `/api/` breaks federation, because other servers are not browsers. Jobs do not come through Cloudflare. The module adds no challenge and turns off Browser Integrity Check, but it does not manage Bot Fight Mode. Do not turn on "I'm Under Attack" for the same reason.
- **Email Address Obfuscation can stay on.** It rewrites email addresses in HTML into `[email protected]` and adds a script to restore them, which the server's Content-Security-Policy refuses. The server's own pages, such as the one that says where the confirmation email went, mark their content so that it leaves the addresses alone.
- **Turn on Always Use HTTPS** in the dashboard if you want `http://` redirected. It covers the whole zone, so the module leaves it to you.
- **Timeouts**: Cloudflare answers `524` when the origin sends nothing for 125 seconds. Jobs are not affected, since they call the `run.app` URL directly. Streams send a heartbeat every 30 seconds, under the 900-second idle limit. Whether it buffers streams on an ordinary proxied host is unverified.
- **Uploads**: 100 MB on Free and Pro, above Cloud Run's 32 MiB, which remains the limit.
- **Video**: Cloudflare's terms restrict serving video and a disproportionate amount of large files on Free, Pro, and Business, and it may redirect the content or take other action. Decide this before you cache video on the media host.

**A deleted file stays cached.** The media host follows the server's `Cache-Control`, so a deleted local file can stay visible for up to a year, and a remote one for `remote_media_cache_ttl_seconds`. The server does not purge it. When something must disappear, purge it by hand, under **Caching > Configuration > Custom Purge** in the dashboard, or:

```sh
curl https://api.cloudflare.com/client/v4/zones/$ZONE_ID/purge_cache \
  -H 'Content-Type: application/json' \
  -H "Authorization: Bearer $CLOUDFLARE_API_TOKEN" \
  -d '{"files": ["https://media.example.org/media/<path>"]}'
```

A proxy URL holds its `sig` in the query string, which is part of what is cached, so give the whole URL.

## Changing the KEK backend

Changing `kek.kind` is one line in `main.tf`, but on an instance with data it is not free. The database holds secrets wrapped with the current key, so an instance that loses it can no longer read them, and every account's keys are among them.

Follow [Move between the local KEK and a KMS](https://mycroblog.dev/next/operations/key-management/#move-between-the-local-kek-and-a-kms). From the secret to Cloud KMS, keep the current KEK as `kek_previous` while the secrets move: add `secrets = ["kek_previous"]`, and fill the secret `my-kek-previous` with the current KEK. Run `my kek rewrap` through [the console](#the-console), then remove it when `my kek status` no longer counts `local:` keys. Keep the KEK for as long as you keep database backups from before the rewrap.

On a new instance with no data, nothing needs to move.

## Limits

- **Uploads**: Cloud Run refuses an HTTP/1 request above 32 MiB, and the server speaks HTTP/1.1. The module therefore sets `MY_MEDIA_MAX_AV_BYTES` to 30 MiB, against the default of 100 MiB, so that a larger upload gets the server's own answer.
- **Streams**: the request timeout, 15 minutes by default, ends an open stream, and the client connects again.
- **Client addresses**: the rate limits rely on `MY_TRUSTED_PROXIES`, which the module sets from the ingress. No document we have read says what Cloud Run adds to `X-Forwarded-For` for a direct request or what peer address a container sees, and the container contract says nothing about either, so `169.254.0.0/16` is an assumption. The external load balancer's documented form is `[<supplied>,]<client-ip>,<lb-ip>`. Check the addresses in the first request logs: a client IP that is a `169.254` address or a Google address means that the setting is wrong for your project.
- **Public access**: the service grants `roles/run.invoker` to `allUsers`, which an organization policy on domain-restricted sharing refuses. Such a project needs an exception.

## Costs

A server costs money. These figures are a guide to what to expect and to where care reduces it, not limits that the deployment is held to. They are approximate list prices for one region, from 2026-10 and 2026-11. Check them on the [Cloud Run](https://cloud.google.com/run/pricing) and [Neon](https://neon.com/pricing) pricing pages. Compute is free per billing account up to 180,000 vCPU-seconds and 360,000 GiB-seconds a month.

| Part | Idle | What adds to it |
| --- | --- | --- |
| Load balancer | About $18 a month, not confirmed on the pricing page | A charge per GB; see [How traffic reaches the service](#how-traffic-reaches-the-service) |
| Neon, on the Launch plan | About $19 a month, with the default tick | Storage at $0.35 per GB-month. `database.kind = cloud-sql` instead has a fixed cost of about $9.40 a month, for a smaller machine |
| Cloud Run | $0: min instances is 0 and CPU is billed only during requests | Each open stream keeps an instance billed; see below |
| Cloud Tasks | $0 | 1 million operations free, then $0.40 per million. A job takes about 2 |
| Cloud Scheduler | $0: 3 jobs free per billing account | $0.10 per job above that |
| Cloud Storage | About $0.02 per GiB a month | 5 GiB are free only in `us-east1`, `us-west1`, and `us-central1`. Media goes out through Cloud Run |
| Pub/Sub | $0: 10 GiB free | Only while streams are open |
| Secret Manager | Cents | A few free versions, then a few cents per version |

**The tick keeps Neon awake.** Each tick reads and writes the database, and Neon stops a compute only after 5 minutes without activity, so with the default `* * * * *` the compute never stops. That is 730 hours a month, or 182.5 CU-hours at 0.25 CU, which is the $19 above. The tick stays at every minute so that periodic jobs run on time, and a lost wake-up signal is recovered soon.

**An open stream keeps an instance billed.** Under request-based billing, an instance is billed while it handles any request, and the real-time updates are one long request. One client that keeps its stream open all month costs one instance around the clock: about $60 a month at 1 vCPU and 512 MiB, after the free allowance. More streams share the instance, up to `concurrency`. If streams stay open most of the time, compare with instance-based billing, or with a small VM and [Docker Compose](https://mycroblog.dev/next/operations/deploy-docker-compose/).

### Where care reduces it

- **The domain mapping** in place of the load balancer takes the $18 away, with [the trade-offs above](#how-traffic-reaches-the-service). It suits trying a deployment.
- **Neon's Free plan** takes the $19 away, and a small instance can run on it, with these trade-offs:
  - It allows 100 CU-hours a month, which the default tick uses up after about 17 days. Stay inside it with a longer schedule, such as `queue = { tick_schedule = "*/10 * * * *" }`: at most half the time awake, about 91 CU-hours, before anything else wakes it. Periodic jobs then run up to 10 minutes late, and a lost wake-up signal is recovered later.
  - A federated server receives deliveries around the clock, which also wakes the database, so a busy instance outgrows it whatever the schedule.
  - It holds 1 GB per project and a 6-hour history to restore from, and its compute always stops after 5 minutes idle, so the first request after that waits for it.
