clover's git

the-knife

1	---
2	title: Apps
3	description: A global namespace containing Machines, Services, Secrets, IPs, and certificates.
4	---
5
6	A [`Fly.App`](/providers/fly/app) is a global namespace in your
7	account. It contains Machines, Services, Secrets, IPs, and
8	certificates.
9
10	A [Service](/fly/compute/services) creates and manages its own App,
11	so you do not declare one to deploy a Service. Declare a `Fly.App`
12	when you need one directly:
13
14	- [Machines](/fly/compute/machines) run in an App you declare.
15	- [`Fly.Secret`](/fly/data/secrets), `SecretKey`,
16	[`Fly.Certificate`](/fly/networking#use-your-own-hostname), and
17	[`IpAssignment`](/fly/networking#addresses-for-a-shared-app) attach
18	to a `Fly.App`, not to a Service's own App.
19	- Several Services share one hostname, secrets, or domain — see
20	[Group Services in one App](/fly/compute/services#group-services-in-one-app).
21
22	## Create an App
23
24	Alchemy generates a unique name unless you pass one.
25
26	```typescript
27	const site = yield* Fly.App("Site");
28	```
29
30	`url` is `https://{appName}.fly.dev`. Nothing answers there until a
31	[Machine](/fly/compute/machines) or a grouped
32	[Service](/fly/compute/services#group-services-in-one-app) publishes
33	a proxy service and the App has an
34	[IP assignment](/fly/networking#addresses-for-a-shared-app).
35
36	:::note
37	Prefer omitting `name` in tests and CI so names stay unique and
38	reclaimable.
39	:::
40
41	## A stable hostname
42
43	Pass `name` when you need a stable `fly.dev` hostname.
44
45	```typescript
46	const site = yield* Fly.App("Site", {
47	name: "my-site",
48	});
49	```
50
51	:::caution[Changing `name` replaces the App]
52	Fly cannot have two Apps with the same name. Alchemy deletes the
53	old App first, then creates the new one.
54	:::
55
56	## Organization
57
58	Org defaults to the current token. Pass `orgSlug` to pin it.
59
60	```diff lang="typescript"
61	const site = yield* Fly.App("Site", {
62	name: "my-site",
63	+ orgSlug: "my-org",
64	});
65	```
66
67	:::caution[Changing `orgSlug` replaces the App]
68	The App is created in the new org. The old App is deleted.
69	:::
70
71	## Subdomains
72
73	`enableSubdomains: true` turns on `*.{appName}.fly.dev`.
74
75	```diff lang="typescript"
76	const site = yield* Fly.App("Site", {
77	name: "my-site",
78	orgSlug: "my-org",
79	+ enableSubdomains: true,
80	});
81	```
82
83	:::note[Create-only]
84	Flipping `enableSubdomains` later is ignored.
85	:::
86
87	## Isolated network
88
89	`network` is an optional 6PN name.
90
91	```diff lang="typescript"
92	const site = yield* Fly.App("Site", {
93	name: "my-site",
94	orgSlug: "my-org",
95	enableSubdomains: true,
96	+ network: "private",
97	});
98	```
99
100	:::caution[Changing `network` replaces the App]
101	The App is recreated on the new network.
102	:::
103
104	## Module-scope declarations
105
106	Declare the App once. Pass it into every child.
107
108	```typescript
109	// src/app.ts
110	import * as Fly from "alchemy/Fly";
111
112	export const Site = Fly.App("Site");
113	```
114
115	Resource-valued props accept the resource or an Effect producing
116	it. Do not unwrap it just to pass it along.
117
118	## Destroy
119
120	`alchemy destroy` deletes children, then the App.
121
122	## Where next
123
124	[Services](/fly/compute/services) own their App by default and join
125	one with `app`. [Machines](/fly/compute/machines) run a raw image in
126	an App. [IPs & certificates](/fly/networking) covers addresses and
127	domains on an App. The [`App` reference](/providers/fly/app) lists
128	every prop.