diff --git a/blueprints/index.html.erb b/blueprints/index.html.erb index f7aa7a3fa1..3b0ea252eb 100644 --- a/blueprints/index.html.erb +++ b/blueprints/index.html.erb @@ -10,12 +10,15 @@ nav: firecracker
- A new—and growing!—library of “blueprints” showing how to run, design, build, and deploy different kinds of apps on Fly.io. This isn’t just a showcase for stuff we’ve built, but a collection of patterns and examples that you can can apply in your own projects. + A new—and growing!—library of "blueprints" showing how to run, design, build, and deploy different kinds of apps on Fly.io. This isn't just a showcase for stuff we've built, but a collection of patterns and examples that you can can apply in your own projects.
+
+### Router app(s)
+
+Your router app handles all incoming wildcard traffic. Its responsibility is simple:
+
+- Extract subdomains (like `alice.example.com` → `alice-123`).
+- Look up the correct app (and optionally machine ID) for that user.
+- Issue a `fly-replay` header directing the Fly Proxy to [internally redirect the request](https://fly.io/docs/networking/dynamic-request-routing) (this should add no more than ~10 milliseconds of latency).
+- Make sure you've added [a wildcard domain](https://fly.io/docs/networking/custom-domain/#get-certified) (*.example.com) to your router app (read more about the [certificate management endpoint here](https://fly.io/docs/networking/custom-domain-api/)).
+
+### User apps
+
+Creating apps dynamically for each user at request time can be slow. To ensure fast provisioning:
+
+- **Pre-create** a pool of Fly apps and machines ahead of time (using the [Fly Machines API or CLI](https://fly.io/docs/apps/overview/)).
+- Store app details (e.g., app_name: `alice-123`) in a datastore accessible to your router app.
+- Assign apps to users at provisioning time.
+
+**Fly Machines**
+
+You'll want to spin up at least one Machine per user app (but apps can have as many Machines as needed). If your dev environments need persistent storage (data that should survive Machine restarts):
+
+- Attach Fly Volumes to each machine at creation time.
+- Keep in mind that machine restarts clear temporary filesystem state but preserve volume data.
+- Learn more about the [Machines API resource](https://fly.io/docs/machines/api/machines-resource/) and the [Volumes API resource](https://fly.io/docs/machines/api/volumes-resource/).
+
+## Pointers & Footguns
+
+- **Machines & volumes are tied to physical hardware:** hardware failures can destroy machines and attached volumes. **Always persist important user data** (code, config, outputs) to external storage (like [Tigris Data](https://fly.io/docs/tigris/#main-content-start) or AWS S3).
+- **Your users will break their environments:** pre-create standby machines to handle hardware & runtime failures, or the inevitable user or robot poisoned environment. Pre-create standby machines that you can quickly activate in these scenarios.
+- **Machine restarts reset ephemeral filesystem:** the temporary Fly Machine filesystem state resets on Machine restarts, ensuring clean environments. However, volume data remains persistent, making it useful for retaining user progress or state.