The best way to control Claude Code, Codex and more from any computer or phone
Mirrored from https://github.com/Camo67/t3code.git
Synced Nov 21, 04:45 UTC
| 1 | --- |
| 2 | title: "Part 4: Stages" |
| 3 | description: Deploy isolated dev, staging, and prod copies of your stack with --stage, and tune Cloud Run per stage. |
| 4 | sidebar: |
| 5 | order: 4 |
| 6 | --- |
| 7 | |
| 8 | import Terminal from "../../../../components/Terminal.astro"; |
| 9 | |
| 10 | In [Part 3](/gcp/tutorial/part-3) you tested a deployed Stack. So far |
| 11 | everything lands in one environment. **Stages** are separate copies of |
| 12 | the same Stack: one per developer, per environment, and (in |
| 13 | [Part 5](/gcp/tutorial/part-5)) per pull request. |
| 14 | |
| 15 | ## The default stage |
| 16 | |
| 17 | Without `--stage`, Alchemy deploys to `live_$USER`: |
| 18 | |
| 19 | ```sh |
| 20 | $ whoami |
| 21 | sam |
| 22 | |
| 23 | $ bun alchemy deploy |
| 24 | # deploys to stage `live_sam` |
| 25 | ``` |
| 26 | |
| 27 | Every developer gets a personal copy with no setup. The stage comes |
| 28 | from, in order: |
| 29 | |
| 30 | 1. the `--stage <name>` flag |
| 31 | 2. the `ALCHEMY_STAGE` environment variable |
| 32 | 3. `live_${USER}` (or `live_${USERNAME}` on Windows) |
| 33 | |
| 34 | ## Deploy a second stage |
| 35 | |
| 36 | ```sh |
| 37 | bun alchemy deploy --stage staging |
| 38 | ``` |
| 39 | |
| 40 | <Terminal content={`[u]Plan[/u]: [g]2 to create[/g] |
| 41 | [g]+[/g] [b]Api[/b] [d](GCP.Run.Service)[/d] |
| 42 | [g]+[/g] [b]Bucket[/b] [d](GCP.Storage.Bucket)[/d] |
| 43 | |
| 44 | Proceed? |
| 45 | ◉ Yes ○ No |
| 46 | [g]✓[/g] [b]Bucket[/b] [d](GCP.Storage.Bucket)[/d] [g]created[/g] |
| 47 | [g]✓[/g] [b]Api[/b] [d](GCP.Run.Service)[/d] [g]created[/g] |
| 48 | { |
| 49 | [s2]url: "https://myapp-staging-api-d4e5f6-uc.a.run.app", |
| 50 | }`} /> |
| 51 | |
| 52 | `staging` gets its own Bucket, its own service, its own service |
| 53 | account, and its own URL. `live_sam` is untouched. |
| 54 | |
| 55 | ## How stages stay apart |
| 56 | |
| 57 | Each stage has its own state and its own resource names. The stage is |
| 58 | part of every generated name, so `prod` and `live_sam` never collide in |
| 59 | the same project. |
| 60 | |
| 61 | Deploying or destroying one stage never touches another: |
| 62 | |
| 63 | ```sh |
| 64 | bun alchemy deploy --stage prod |
| 65 | bun alchemy deploy --stage pr-42 |
| 66 | bun alchemy destroy --stage pr-42 # only removes pr-42 |
| 67 | ``` |
| 68 | |
| 69 | Stage names must match `[a-z0-9][-_a-z0-9]*`. |
| 70 | |
| 71 | ## Configure per stage |
| 72 | |
| 73 | Keep one warm instance in prod so the first request after a quiet |
| 74 | period doesn't wait for a cold start. `Stack.useSync` gives the props |
| 75 | the current stage: |
| 76 | |
| 77 | ```diff lang="typescript" |
| 78 | // src/api.ts |
| 79 | import * as GCP from "@alchemy.run/gcp"; |
| 80 | +import { Stack } from "alchemy/Stack"; |
| 81 | import * as Effect from "effect/Effect"; |
| 82 | |
| 83 | export default class Api extends GCP.Function<Api>()( |
| 84 | "Api", |
| 85 | - { main: import.meta.url, invokerIamDisabled: true }, |
| 86 | + Stack.useSync((stack) => ({ |
| 87 | + main: import.meta.url, |
| 88 | + invokerIamDisabled: true, |
| 89 | + scaling: { minInstanceCount: stack.stage === "prod" ? 1 : 0 }, |
| 90 | + })), |
| 91 | Effect.gen(function* () { |
| 92 | // ... |
| 93 | }), |
| 94 | ) {} |
| 95 | ``` |
| 96 | |
| 97 | `alchemy deploy --stage prod` keeps one instance running. Every other |
| 98 | stage scales to zero. |
| 99 | |
| 100 | ## Destroy a stage |
| 101 | |
| 102 | ```sh |
| 103 | bun alchemy destroy --stage staging |
| 104 | ``` |
| 105 | |
| 106 | The plan lists everything in `staging` for deletion, including the |
| 107 | service account Alchemy created for the service. |
| 108 | |
| 109 | ## Stages in tests |
| 110 | |
| 111 | Tests default to `test_$USER`. Set the stage per file so parallel CI |
| 112 | runs don't collide: |
| 113 | |
| 114 | ```diff lang="typescript" |
| 115 | // test/integ.test.ts |
| 116 | const { test, beforeAll, afterAll, deploy, destroy } = Test.make({ |
| 117 | providers: GCP.providers(), |
| 118 | state: GCP.state(), |
| 119 | + stage: `pr-${process.env.PR_NUMBER}`, |
| 120 | }); |
| 121 | ``` |
| 122 | |
| 123 | See [Test harness → stage](/testing/test-harness#stage) for the |
| 124 | per-call form. |
| 125 | |
| 126 | ## Stages and projects |
| 127 | |
| 128 | Stages separate **what** is deployed. [Profiles](/environments/profiles) |
| 129 | choose **where**: which GCP project and credentials. Pair a `prod` |
| 130 | stage with a `prod` profile pointing at a separate project: |
| 131 | |
| 132 | ```sh |
| 133 | bun alchemy deploy --stage prod --profile prod |
| 134 | bun alchemy deploy --stage pr-42 --profile default |
| 135 | ``` |
| 136 | |
| 137 | ## Recap |
| 138 | |
| 139 | You now have: |
| 140 | |
| 141 | - A personal `live_<user>` stage for every plain `alchemy deploy` |
| 142 | - A `staging` stage deployed and destroyed with `--stage` |
| 143 | - A warm instance in prod only, via `Stack.useSync` |
| 144 | - Tests pinned to their own stage |
| 145 | |
| 146 | In [Part 5](/gcp/tutorial/part-5), GitHub Actions deploys `prod` on |
| 147 | every push to `main` and a `pr-<n>` preview for every pull request. |