@devries-cameron20 / t3code Mirror · read-only
Fork 0

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

main
mdx 193 lines 5.85 KB
Raw
1 ---
2 title: Getting started
3 description: Issue a staging TLS certificate with Let's Encrypt and an existing Cloudflare DNS zone.
4 ---
5
6 This guide issues a certificate for a domain you control. It uses Let's Encrypt
7 staging, so you can validate the deployment without consuming production issuance
8 limits. The resulting certificate is deliberately **not trusted by browsers**.
9
10 ## Prepare the project
11
12 Install Alchemy and the matching Effect version using [Cloudflare setup](/cloudflare/setup),
13 then add `@alchemy.run/acme`.
14 You need an active Cloudflare DNS zone, its zone ID, and credentials that can read,
15 create, and delete DNS records in that zone. The domain's authoritative nameservers
16 must already point to Cloudflare.
17
18 Use a domain you own wherever this guide says `example.com`. Set
19 `CLOUDFLARE_ZONE_ID` in your project's `.env` to the zone ID from its Cloudflare
20 dashboard. This example references the existing zone by ID; it does not create,
21 adopt, modify the settings of, or delete the zone itself.
22
23 ## Create the stack
24
25 Create `alchemy.run.ts`:
26
27 ```typescript
28 import * as Alchemy from "alchemy";
29 import * as Effect from "effect/Effect";
30 import * as Layer from "effect/Layer";
31
32 export default Alchemy.Stack(
33 "Certificates",
34 { providers: Layer.empty, state: Alchemy.localState() },
35 Effect.gen(function* () {
36 return {};
37 }),
38 );
39 ```
40
41 The stack groups the certificate resources and persists their state locally.
42 Treat that state as secret material and keep it out of source control. For a
43 shared deployment runner, use a protected [remote state store](/state-store).
44
45 ## Register the providers
46
47 ```diff lang="typescript"
48 +import * as ACME from "@alchemy.run/acme";
49 +import * as Cloudflare from "@alchemy.run/cloudflare";
50
51 export default Alchemy.Stack(
52 "Certificates",
53 - { providers: Layer.empty, state: Alchemy.localState() },
54 + {
55 + providers: Layer.mergeAll(ACME.providers(), Cloudflare.providers()),
56 + state: Alchemy.localState(),
57 + },
58 ```
59
60 `ACME.providers()` manages accounts and certificates, and
61 `Cloudflare.providers()` includes the Cloudflare DNS solver used to prove
62 control of the domain.
63
64 ## Connect Cloudflare
65
66 ```sh
67 alchemy profile edit --add Cloudflare
68 ```
69
70 Select the Cloudflare account containing your zone. You can use OAuth or a
71 suitably scoped API token; [Cloudflare setup](/cloudflare/setup) also documents
72 non-interactive environment credentials for CI.
73
74 ## Create an ACME account
75
76 Inside the stack's `Effect.gen`, add the account before `return`:
77
78 ```diff lang="typescript"
79 Effect.gen(function* () {
80 + const account = yield* ACME.Account("Issuer", {
81 + ca: ACME.LetsEncryptStaging,
82 + contact: ["mailto:ops@example.com"],
83 + termsOfServiceAgreed: true,
84 + });
85 return {};
86 }),
87 ```
88
89 Replace the contact address with yours and review the CA's terms before agreeing.
90 The account gets its own signing key, which Alchemy persists in stack state and
91 reuses on subsequent deployments.
92
93 ## Request the certificate
94
95 ```diff lang="typescript"
96 +import * as Config from "effect/Config";
97
98 const account = yield* ACME.Account("Issuer", {
99 ca: ACME.LetsEncryptStaging,
100 contact: ["mailto:ops@example.com"],
101 termsOfServiceAgreed: true,
102 });
103 + const certificate = yield* ACME.Certificate("Site", {
104 + account,
105 + identifiers: ["example.com"],
106 + solver: Cloudflare.ACME.ZoneSolver({
107 + zoneId: Config.String("CLOUDFLARE_ZONE_ID"),
108 + }),
109 + });
110 ```
111
112 The solver publishes a temporary `_acme-challenge.example.com` TXT record.
113 It waits for propagation before asking the CA to validate it, then removes that
114 challenge record. Existing unrelated TXT values are preserved.
115
116 ## Return certificate metadata
117
118 ```diff lang="typescript"
119 - return {};
120 + return {
121 + serial: certificate.serial,
122 + expires: certificate.notAfter,
123 + };
124 ```
125
126 Return metadata rather than private keys. The PEM chain and redacted key remain
127 available as resource outputs for a [TLS consumer](/acme/using-certificates).
128
129 ## Deploy to a development stage
130
131 ```sh
132 alchemy deploy --stage dev
133 ```
134
135 Allow time for DNS validation: Cloudflare's solver includes a 60-second wait to
136 let cached challenge values expire. A successful deployment returns the serial
137 number and expiry. It does not configure a website or an HTTPS listener.
138
139 ## Review the complete file
140
141 The steps above produce this `alchemy.run.ts`:
142
143 ```typescript
144 import * as Alchemy from "alchemy";
145 import * as ACME from "@alchemy.run/acme";
146 import * as Cloudflare from "@alchemy.run/cloudflare";
147 import * as Config from "effect/Config";
148 import * as Effect from "effect/Effect";
149 import * as Layer from "effect/Layer";
150
151 export default Alchemy.Stack(
152 "Certificates",
153 {
154 providers: Layer.mergeAll(ACME.providers(), Cloudflare.providers()),
155 state: Alchemy.localState(),
156 },
157 Effect.gen(function* () {
158 const account = yield* ACME.Account("Issuer", {
159 ca: ACME.LetsEncryptStaging,
160 contact: ["mailto:ops@example.com"],
161 termsOfServiceAgreed: true,
162 });
163 const certificate = yield* ACME.Certificate("Site", {
164 account,
165 identifiers: ["example.com"],
166 solver: Cloudflare.ACME.ZoneSolver({
167 zoneId: Config.String("CLOUDFLARE_ZONE_ID"),
168 }),
169 });
170 return {
171 serial: certificate.serial,
172 expires: certificate.notAfter,
173 };
174 }),
175 );
176 ```
177
178 ## Clean up the development stack
179
180 ```sh
181 alchemy destroy --stage dev
182 ```
183
184 Destruction deactivates the ACME account and removes the stack's certificate
185 state. By default it does not revoke an issued certificate. The existing DNS
186 zone is not a managed resource in this example and remains intact. Read
187 [Renewal & revocation](/acme/renewal) before choosing a production deletion policy.
188
189 ## Next steps
190
191 - [Certificate authorities](/acme/certificate-authorities) — switch to a trusted production CA.
192 - [DNS validation](/acme/dns-validation) — add a wildcard or customize propagation.
193 - [Using certificates](/acme/using-certificates) — attach the chain and key to a TLS consumer.