clover's git

the-knife

1	---
2	title: Using certificates
3	description: Upload an ACME certificate to Fly or pass its chain and private key to another TLS consumer.
4	---
5
6	Issuance creates certificate material; it does not create an HTTPS endpoint.
7	A TLS consumer must receive the matching chain and private key, present the
8	certificate for the correct hostname, and reload replacements after renewal.
9
10	## Choose the right output
11
12	| Output | Contents | Typical use |
13	| --- | --- | --- |
14	| `certificate` | Leaf certificate PEM | Revocation or certificate inspection |
15	| `chain` | Full PEM chain, leaf first | TLS server or certificate upload |
16	| `privateKey` | Redacted PKCS#8 private key PEM | TLS server or certificate upload |
17	| `notAfter` | ISO 8601 expiry | Monitoring and renewal scheduling |
18	| `serial` | Certificate serial number | Identifying the installed version |
19
20	The account's `privateKey` is a different key, used to sign ACME requests. A TLS
21	consumer needs the **certificate's** private key, never the account's key.
22
23	## Register Fly's provider
24
25	Start with the [Getting started](/acme/getting-started) stack and add Fly:
26
27	```diff lang="typescript"
28	+import * as Fly from "alchemy/Fly";
29
30	- providers: Layer.mergeAll(ACME.providers(), Cloudflare.providers()),
31	+ providers: Layer.mergeAll(
32	+ ACME.providers(),
33	+ Cloudflare.providers(),
34	+ Fly.providers(),
35	+ ),
36	```
37
38	Connect your Fly account using [Fly setup](/fly/setup). The ACME account and DNS
39	solver remain independent of Fly; only the upload resource uses Fly credentials.
40
41	## Create the destination App
42
43	Inside the stack Effect, before the upload:
44
45	```typescript
46	const app = yield* Fly.App("Site", {});
47	```
48
49	Use your application's existing `App` instead when it already owns the TLS
50	endpoint. Creating an App alone does not start a service or allocate public IPs.
51
52	## Upload the certificate
53
54	After resolving the ACME certificate:
55
56	```typescript
57	yield* Fly.Certificate("SiteTls", {
58	app,
59	hostname: "example.com",
60	kind: "custom",
61	fullchain: certificate.chain,
62	privateKey: certificate.privateKey,
63	});
64	```
65
66	The resource outputs establish a dependency on issuance. After an ACME renewal
67	changes the chain and key, the same deployment updates the Fly upload. Pass the
68	redacted key directly; the provider handles unwrapping it for the API.
69
70	## Review the complete upload stack
71
72	This example uses Let's Encrypt **production** because the destination is a
73	public TLS consumer. First verify DNS issuance with the staging-only getting
74	started example. Replace the hostname, contact address, and zone configuration
75	with your own values:
76
77	```typescript
78	import * as Alchemy from "alchemy";
79	import * as ACME from "alchemy/ACME";
80	import * as Cloudflare from "alchemy/Cloudflare";
81	import * as Fly from "alchemy/Fly";
82	import * as Config from "effect/Config";
83	import * as Effect from "effect/Effect";
84	import * as Layer from "effect/Layer";
85
86	export default Alchemy.Stack(
87	"SiteCertificates",
88	{
89	providers: Layer.mergeAll(
90	ACME.providers(),
91	Cloudflare.providers(),
92	Fly.providers(),
93	),
94	state: Alchemy.localState(),
95	},
96	Effect.gen(function* () {
97	const app = yield* Fly.App("Site", {});
98	const account = yield* ACME.Account("Issuer", {
99	ca: ACME.LetsEncrypt,
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.DNS.AcmeSolver({
107	zoneId: Config.String("CLOUDFLARE_ZONE_ID"),
108	}),
109	});
110	yield* Fly.Certificate("SiteTls", {
111	app,
112	hostname: "example.com",
113	kind: "custom",
114	fullchain: certificate.chain,
115	privateKey: certificate.privateKey,
116	});
117	return { appName: app.appName, expires: certificate.notAfter };
118	}),
119	);
120	```
121
122	## Make the hostname reachable
123
124	Follow [Fly IPs & certificates](/fly/networking) to publish a Service, allocate
125	public IPs, and point the hostname's DNS records at the App. A successful
126	certificate upload is separate from traffic routing. Check the certificate
127	served by `https://example.com` after the routing is ready.
128
129	For ordinary Fly-managed certificates, `Fly.Certificate` with `kind: "acme"`
130	lets Fly handle issuance. Use this independent `ACME.Certificate` plus
131	`kind: "custom"` combination when you need control over the issuing CA or DNS
132	validation and will operate renewal yourself.
133
134	## Pass outputs to another resource
135
136	Alchemy resource props accept outputs directly. If another provider accepts PEM
137	chain and key inputs, pass `certificate.chain` and `certificate.privateKey` to
138	those fields just as in the Fly upload. Follow that provider's expected chain
139	format and supported key algorithms.
140
141	For a consumer outside Alchemy, build an explicit secure delivery process.
142	Store the chain and key as a matching pair, restrict key access, reload the TLS
143	service after renewal, and verify the certificate it serves. Exporting a PEM
144	once does not subscribe the consumer to later resource updates.
145
146	## Upload from an application
147
148	In an initialized Fly Service or Worker, bind the destination App separately
149	from the ACME account:
150
151	```typescript
152	const certificates = yield* Fly.WriteCertificates(Site);
153	```
154
155	Provide `Fly.WriteCertificatesHttp` on the host Effect. `Site` is the same App
156	resource your service uses; the binding transports the necessary app identity
157	and scoped credentials to runtime.
158
159	## Install a runtime-issued certificate
160
161	After `issuer.issue` returns inside a request or job:
162
163	```typescript
164	yield* certificates.upload({
165	hostname: "example.com",
166	fullchain: issued.chain,
167	privateKey: issued.privateKey,
168	});
169	```
170
171	Use the [runtime issuance guide](/acme/runtime) for the account and DNS bindings.
172	The runtime upload is not a `Fly.Certificate` stack resource. Your application
173	must track and renew it; avoid having a deploy-time resource and a runtime job
174	both manage the same App/hostname.
175
176	## Keep removal and revocation separate
177
178	Removing a Fly certificate stops that App from using it but does not revoke it
179	at the issuing CA. Revoking at the CA does not remove the Fly upload. For a
180	runtime-managed certificate, replace or remove the consumer copy first, then
181	call `issuer.revoke` according to your retirement policy.
182
183	See [Renewal & revocation](/acme/renewal), the
184	[Fly Certificate reference](/providers/fly/certificate), and
185	[WriteCertificates reference](/providers/fly/writecertificates) for the separate
186	lifecycle controls.