apps/docs/src/content/docs/guides/deploy-to-cloudflare.md · flagon-io/g1t

| ---------- | ---------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------- |

319

| The base | `services/runner/base/Dockerfile`: Debian, Node, Python, Docker, Go, Rust, Java, .NET and Ruby | When its folder changes, weekly by `runner-base.yml`, or by hand with `build-base` |

320

| The runner | `services/runner/Dockerfile`: the base plus the `g1t-runner` binary | When the binary or the base changes |

321

322

`services/runner/base.json` records the base that was pushed;

323

`npm run test:deploy` fails while it and the base's folder disagree. The

324

runner's image is tagged with a hash of what it is built from, so a deploy

325

makes it only when the registry does not already have it. It is made in

326

the registry, without Docker: the deploy reads the base's manifest,

327

uploads one layer holding the binary, and writes a manifest that names the

328

base's layers and that one, with the entrypoint `services/runner/Dockerfile`

329

gives it. Nothing of the base is downloaded, so the deploy job needs no

330

room for it. If that fails and Docker runs where the deploy does, the

331

image is built from `services/runner/Dockerfile` and pushed instead, and

332

the log shows how full the disk was before and after. A dry run

333

(`build`, or `image --no-push`) builds it with Docker. When nothing

334

the image is built from changed, the deploy leaves running sandboxes

335

alone. When it did, Cloudflare replaces sandboxes on the new image but

336

leaves any that started within the last two hours

337

(`rollout_active_grace_period` in `services/runner/wrangler.jsonc`) to

338

finish first. A workflow job on g1t's machines runs for at most 60

339

minutes, so a deploy never cuts one short.

340

341

The standard sandbox is the instance type `standard-3` (2 vCPU, 8 GiB,

342

16 GB), and so is `runs-on: g1t-2core`, in a class of its own; jobs that

343

ask for `runs-on: g1t-4core`, and `ubuntu-latest` jobs in a public

344

repository, get `standard-4` (4 vCPU, 12 GiB, 20 GB). At

345

the `max_instances` in `services/runner/wrangler.jsonc` (20, 10 and 10),

346

40 sandboxes at once hold 100 vCPU, 360 GiB of memory and 680 GB of disk,

347

which your account's Containers limits for live instances must allow.

348

349

Set the runner Worker's `DOCKER` variable to `off` to give workflow jobs no

350

Docker Engine.

351

352

`CLOUDFLARE_API_TOKEN=<token> node scripts/ops/runner-errors.mjs` sorts the

353

sandboxes' errors over the last 7 days into expected ones (a deploy

354

resetting them, no free capacity, a container that stopped) and ones to

355

read.

356

357

## Docker deployments

358

359

Container apps ([Docker deployments](/guides/deployments/#docker-deployments))

360

run when `CONTAINERS` is `on` in `services/deployments/wrangler.jsonc`, as

361

it is for g1t.sh. On an account without Containers, set it to `off`: a

362

container build then fails, saying so, and a project with a site beside

363

its `Dockerfile` is built as that site.

364

365

The calls follow Cloudflare's API reference and Wrangler's own client.

366

On a new account, deploy a small server (an Express app with a

367

`Dockerfile`, or none) and check each of these:

368

369

1. **The token.** `CLOUDFLARE_API_TOKEN` of `services/deployments` has

370

**Containers: Edit** (and the account has Containers, on Workers Paid).

371

2. **Registry logins.**

372

`POST /accounts/{id}/containers/registries/registry.cloudflare.com/credentials`

373

with `{ "permissions": ["push"], "expiration_minutes": 15 }` answers

374

inside the API's usual `{ success, result }` with a `username` and

375

`password`, and `docker push` succeeds with that login alone, with no

376

`pull` (Docker checks for layers before it uploads them). If it needs

377

`pull`, do not add it: a pull login reads every app's image. Find

378

another way first, such as Cloudflare scoping logins to a repository.

379

3. **Checking a digest.** g1t asks

380

`HEAD https://registry.cloudflare.com/v2/<account>/g1t-<app>/manifests/sha256:…`

381

with a pull login of its own, following a `WWW-Authenticate: Bearer`

382

challenge. It answers 200 for an image that was pushed.

383

4. **The app's Worker.** A script uploaded to the dispatch namespace with

384

`exports: { "G1tApp": { "type": "durable-object", "storage": "sqlite" } }`

385

and `containers: [{ "class_name": "G1tApp" }]` in its metadata is taken,

386

and taken again on the next deploy with nothing changed about the class.

387

5. **Its Durable Object namespace.** The app's Worker's `APP` binding

388

(`GET …/dispatch/namespaces/g1t-deployments/scripts/<app>/bindings`)

389

names its `namespace_id`; failing that,

390

`GET /accounts/{id}/workers/durable_objects/namespaces` lists it with

391

`class` `G1tApp` and `script` the app's name.

392

6. **The Container application.** `POST /accounts/{id}/containers/applications`

393

with `scheduling_policy` `default`, the image by digest, `instance_type`,

394

`max_instances` 1 and `durable_objects.namespace_id` creates it; a

395

rollout (`…/rollouts`, `strategy` `rolling`, `step_percentage` 100,

396

`kind` `full_auto`) moves it to a new image; `DELETE` removes it.

397

7. **Starting.** `ctx.container.start({ env, enableInternet: true })`

398

works under the default policy from a Worker in a dispatch namespace,

399

the container gets its environment, and `getTcpPort(port).fetch()`

400

reaches it; the dispatcher's limits (50 ms of CPU, 50 subrequests) leave

401

room for a page that waits on a container starting.

402

8. **Sleeping and billing.** Five minutes after the last request the

403

container stops (the app's object stops it itself), Cloudflare's billable

404

usage for Containers stops growing, and `container_meters` in the

405

deployments database has the minutes the app's Worker reported, which

406

should be at least what Cloudflare billed for the same time.

407

9. **Pausing and taking down.** A workspace over its limit gets its

408

container app's Worker put back paused, which stops the container, and

409

taking an app down deletes its application before its Worker.

410

10. **Old images.** After a second deploy of the app, the registry's tag

411

list for `<account>/g1t-<app>` has only the two newest builds' tags

412

(`GET /v2/<account>/g1t-<app>/tags/list`), and none once the app is

413

taken down. The account holds 50 GB of images in all.

## Rolling back

- **One unit, at once:** `npx wrangler rollback` in its folder. Revert the

418

commit on `main` too, or the next push brings it back.

419

- **To a commit:** check it out and run

420

`node scripts/deploy.mjs deploy --only <units> --rollback`. Without

421

`--rollback` the tool refuses a unit whose live commit is newer.

422

- **The runner's image:** redeploy the older commit with

423

`--only runner --rollback`; its image is still in the registry.

424

425

## Other one-time setup

426

427

### The dead-letter queue

428

429

Every queue consumer retries a message a fixed number of times, then puts

430

it on `g1t-events-dlq`. Nothing consumes that queue: read it with

431

`npx wrangler queues info g1t-events-dlq`, fix the cause, and replay by

432

hand.

433

434

### OIDC tokens for workflow jobs

435

436

The API issues workflow jobs' [OIDC tokens](/guides/actions/), signed with

437

an RSA key in its secret `ACTIONS_OIDC_KEY`. Without it, jobs get no

tokens.

```sh

openssl genpkey -algorithm RSA -pkeyopt rsa_keygen_bits:2048 -out oidc.pem

442

cd apps/api && npx wrangler secret put ACTIONS_OIDC_KEY < ../../oidc.pem

rm ../../oidc.pem

```

To rotate it, store the current key as `ACTIONS_OIDC_KEY_PREVIOUS`, store

447

a new one as `ACTIONS_OIDC_KEY`, and delete the previous one a day later.

448

For a key that may have leaked, skip keeping the previous one.

449

450

### Telling the status page about deploys

451

452

Restarts during a deploy can look like an outage to the status page's

453

checks. Set the same value as the status Worker's secret

454

`STATUS_DEPLOY_TOKEN` and as the repository's Actions secret

455

`STATUS_DEPLOY_TOKEN`. Deploys then announce their start and finish, and the status page

456

drafts no incident during them or for 3 minutes after.

### Browser push

`node scripts/ops/vapid-keys.mjs` prints a VAPID key pair. Put the public

461

half in `VAPID_PUBLIC_KEY` in `services/notify/wrangler.jsonc` and the

462

private half in the secret `VAPID_PRIVATE_KEY`.

463

464

Pushes to the phone app go through Expo's push service and need nothing

465

set. If the Expo project the app is built from turns on **enhanced push

466

security**, put an Expo access token in the notify Worker's secret

`EXPO_ACCESS_TOKEN`:

```sh

cd services/notify && npx wrangler secret put EXPO_ACCESS_TOKEN

471

```

472

473

For g1t.sh, leave enhanced push security off: every self-hosted g1t

474

pushes to the same app, through the same Expo project, without a token of

475

g1t's. Turning it on stops notifications to phones from every

476

installation but g1t.sh.

477

478

To send phones nothing at all, set `PHONE_PUSH` to `off` in the `vars` of

479

both `services/notify/wrangler.jsonc` and `apps/web/wrangler.jsonc`: the

480

notify Worker sends them nothing, and the site's

481

`/.well-known/g1t.json` tells the app so.

## Rate limits

Every public surface that costs money or sends something is behind a

486

[Workers Rate Limiting](https://developers.cloudflare.com/workers/runtime-apis/bindings/rate-limit/)

487

binding, with the limits on the [rate limits](/reference/rate-limits/)

488

page. The binding's `namespace_id` must be unique in your account. A

489

missing binding, or one that fails, lets requests through.

## Spend guardrails

Cloudflare has no hard spending cap. Besides each workspace's own

494

[limits](/guides/usage-and-billing/), g1t watches the platform as a whole:

495

496

- **The hourly watch.** At a quarter past each hour, billing reads the

497

hour before from Cloudflare's GraphQL Analytics API: Workers requests

498

and CPU, D1 rows, Queue operations, Durable Objects, KV and Artifacts.

499

It needs `CLOUDFLARE_BILLING_TOKEN` (or `CLOUDFLARE_USAGE_TOKEN`) with

500

Account Analytics Read. An hour over its threshold, or over ten times

501

the week's median hour, is emailed to `COSTS_ALERT_EMAIL`.

502

- **Thresholds** are the `PLATFORM_HOURLY_*` variables in

503

`services/billing/wrangler.jsonc`; `0` turns one off. A breach at five

504

times its threshold pauses the kinds of work in `AUTO_PAUSE`.

505

- **The platform pause** stops a kind of work everywhere: `compute`

506

(sandboxes), `schedules`, `indexing` or `renders` (social cards). Staff

507

pause and resume in sudo, under **Costs & margin**. Work already

508

running finishes, and if the pause cannot be read, nothing is paused.

509

- **Check the watch's queries** after changing them:

510

`CLOUDFLARE_API_TOKEN=<token> node scripts/ops/platform-usage.mjs`. It

511

exits 1 and names any dataset that errored or answered empty.

512

513

In Cloudflare's dashboard, which no code can set, add **Billable Usage**

514

notifications for each product g1t uses, a monthly **Budget alert**, and a

515

notification destination that reaches someone.

## Logs

Each Worker keeps a share of its invocations' logs, set by

520

`head_sampling_rate` in its `wrangler.jsonc`: every one for billing,

521

identity, runner, actions, deployments, status and sudo, a quarter for

522

repos and work, which every page asks, and a tenth for the rest. Metrics

523

are not sampled. To chase a rare error on a sampled Worker, raise its rate

524

to 1 while you look.

525

526

Slow work in repos logs itself as fields, so the invocations kept can be

527

counted by what was slow: an RPC answer that took a second or more logs

528

`rpc` (the method) and `answered_ms`, and a slow or partial About run logs

529

`about_run` (the repository's id), `took_ms` and `partial`. In Workers

530

Logs, filter `g1t-repos` on `answered_ms` greater than 0, and multiply

531

what you count by four.