more details and fixups

Author: emily-shen

public/__redirects

@@ -2371,3 +2371,9 @@
 /realtime/realtimekit/get-started /realtime/realtimekit/getting-started/ 302
 /realtime/introduction /realtime/realtimekit/introduction 302
 /realtime/concepts /realtime/realtimekit/concepts 302
+
+# Containers
+/containers/platform-details/#limits /containers/platform-details/limits 301
+/containers/image-management /containers/platform-details/image-management 301
+/containers/scaling-and-routing /containers/platform-details/scaling-and-routing 301
+/containers/architecture /containers/platform-details/architecture 301

src/content/docs/containers/beta-info.mdx

@@ -38,7 +38,6 @@ We plan to automatically reduce log noise in the future.
 
 The dashboard will be updated to show:
 
-- the status of Container rollouts
 - links from Workers to their associated Containers
 
 ### Co-locating Durable Objects and Containers

src/content/docs/containers/examples/env-vars-and-secrets.mdx

@@ -151,3 +151,7 @@ export default {
 	},
 };
 ```
+
+## Build-time environment variables
+
+Finally, you can also set build-time environment variables that are only available when building the container image via the `image_vars` field in the Wrangler configuration.

src/content/docs/containers/faq.mdx

@@ -85,7 +85,7 @@ on image size and code execution time, among other factors.
 
 ## How do I use an existing container image?
 
-See [image management documentation](/containers/image-management/#using-existing-images) for details.
+See [image management documentation](/containers/platform-details/image-management/#using-existing-images) for details.
 
 ## Is disk persistent? What happens to my disk when my container sleeps?
 

src/content/docs/containers/get-started.mdx

@@ -17,7 +17,7 @@ This example Worker should give you a sense for simple Container use, and provid
 ### Ensure Docker is running locally
 
 In this guide, we will build and push a container image alongside your Worker code. By default, this process uses
-[Docker](https://www.docker.com/) to do so. You must have Docker running locally when you run `wrangler deploy`. For most people, the best way to install Docker is to follow the [docs for installing Docker Desktop](https://docs.docker.com/desktop/).
+[Docker](https://www.docker.com/) to do so. You must have Docker running locally when you run `wrangler deploy`. For most people, the best way to install Docker is to follow the [docs for installing Docker Desktop](https://docs.docker.com/desktop/). Other tools like [Colima](https://github.com/abiosoft/colima) may also work.
 
 You can check that Docker is running properly by running the `docker info` command in your terminal. If Docker is running, the command will succeed. If Docker is not running,
 the `docker info` command will hang or return an error including the message "Cannot connect to the Docker daemon".
@@ -29,9 +29,11 @@ the `docker info` command will hang or return an error including the message "Ca
 
 Run the following command to create and deploy a new Worker with a container, from the starter template:
 
-```sh
-npm create cloudflare@latest -- --template=cloudflare/templates/containers-template
-```
+<PackageManagers
+	type="create"
+	pkg="cloudflare@latest"
+	args={"--template=cloudflare/templates/containers-template"}
+/>
 
 When you want to deploy a code change to either the Worker or Container code, you can run the following command using [Wrangler CLI](/workers/wrangler/):
 
@@ -40,7 +42,7 @@ When you want to deploy a code change to either the Worker or Container code, yo
 When you run `wrangler deploy`, the following things happen:
 
 - Wrangler builds your container image using Docker.
-- Wrangler pushes your image to a [Container Image Registry](/containers/image-management/) that is automatically
+- Wrangler pushes your image to a [Container Image Registry](/containers/platform-details/image-management/) that is automatically
   integrated with your Cloudflare account.
 - Wrangler deploys your Worker, and configures Cloudflare's network to be ready to spawn instances of your container
 
@@ -67,7 +69,7 @@ And see images deployed to the Cloudflare Registry with the following command:
 
 Now, open the URL for your Worker. It should look something like `https://hello-containers.YOUR_ACCOUNT_NAME.workers.dev`.
 
-If you make requests to the paths `/container/1` or `/container/2`, these requests are routed to specific containers.
+If you make requests to the paths `/container/1` or `/container/2`, your Worker routes requests to specific containers.
 Each different path after "/container/" routes to a unique container.
 
 If you make requests to `/lb`, you will load balanace requests to one of 3 containers chosen at random.

src/content/docs/containers/index.mdx

@@ -45,7 +45,8 @@ With Containers you can run:
 - Applications and libraries that require a full filesystem, specific runtime, or Linux-like environment
 - Existing applications and tools that have been distributed as container images
 
-Container instances are spun up on-demand and controlled by code you write in your [Worker](/workers).  Instead of chaining together API calls or writing Kubernetes operators, you just write JavaScript:
+Container instances are spun up on-demand and controlled by code you write in your [Worker](/workers). Instead of chaining together API calls or writing Kubernetes operators, you just write JavaScript:
+
 <Tabs>
 	<TabItem label="Worker Code">
 ```js
@@ -57,14 +58,14 @@ export class MyContainer extends Container {
 }
 
 async fetch(request, env) {
-	const { "session-id": sessionId } = await request.json();
-	// Get the container instance for the given session ID
-	const containerInstance = getContainer(env.MY_CONTAINER, sessionId)
-	// Pass the request to the container instance on its default port
-	return containerInstance.fetch(request);
+const { "session-id": sessionId } = await request.json();
+// Get the container instance for the given session ID
+const containerInstance = getContainer(env.MY_CONTAINER, sessionId)
+// Pass the request to the container instance on its default port
+return containerInstance.fetch(request);
 }
 
-```
+````
 </TabItem>
 <TabItem label="Worker Config">
 <WranglerConfig>
@@ -77,7 +78,7 @@ async fetch(request, env) {
     {
       "class_name": "MyContainer",
       "image": "./Dockerfile",
-      "instances": 5,
+      "max_instances": 5,
     }
   ],
   "durable_objects": {
@@ -97,14 +98,21 @@ async fetch(request, env) {
 		}
 	],
 }
-```
+````
 
 </WranglerConfig>
 </TabItem>
 </Tabs>
 
-
- <LinkButton variant="primary" href="/containers/get-started/">Get started</LinkButton> <LinkButton variant="secondary" href="https://dash.cloudflare.com/?to=/:account/workers/containers">Containers dashboard</LinkButton>
+<LinkButton variant="primary" href="/containers/get-started/">
+	Get started
+</LinkButton>
+<LinkButton
+	variant="secondary"
+	href="https://dash.cloudflare.com/?to=/:account/workers/containers"
+>
+	Containers dashboard
+</LinkButton>
 
 ---
 
@@ -146,7 +154,11 @@ regional placement, Workflow and Queue integrations, AI-generated code execution
 	containers with Wrangler.
 </LinkTitleCard>
 
-<LinkTitleCard title="Limits" href="/containers/platform-details/#limits" icon="seti:lock">
+<LinkTitleCard
+	title="Limits"
+	href="/containers/platform-details/#limits"
+	icon="seti:lock"
+>
 	Learn about what limits Containers have and how to work within them.
 </LinkTitleCard>
 
@@ -160,4 +172,3 @@ regional placement, Workflow and Queue integrations, AI-generated code execution
 </LinkTitleCard>
 
 </CardGrid>
-

src/content/docs/containers/platform-details/architecture.mdx

@@ -5,10 +5,18 @@ sidebar:
   order: 1
 ---
 
-## How and where containers run
+## How Containers run
+
+Each container instance runs inside its own VM, which provides strong
+isolation from other workloads running on Cloudflare's network. Containers
+should be built for the `linux/amd64` architecture, and should stay within
+[size limits](/containers/platform-details/limits). Logging, metrics collection, and
+networking are automatically set up on each container.
+
+## Where Containers run
 
 After you deploy a Worker that uses a Container, your image is uploaded to
-[Cloudflare's Registry](/containers/image-management) and distributed globally to Cloudflare's Network.
+[Cloudflare's Registry](/containers/platform-details/image-management) and distributed globally to Cloudflare's Network.
 Cloudflare will pre-schedule instances and pre-fetch images across the globe to ensure quick start
 times when scaling up the number of concurrent container instances. This allows you to call
 `env.YOUR_CONTAINER.get(id)` and get a new instance quickly without worrying
@@ -26,11 +34,29 @@ locations, some container instances may be started in locations that are farther
 the end-user. This is done to ensure that the container instance starts quickly. You are
 only charged for actively running instances and not for any unused pre-warmed images.
 
-Each container instance runs inside its own VM, which provides strong
-isolation from other workloads running on Cloudflare's network. Containers
-should be built for the `linux/amd64` architecture, and should stay within
-[size limits](/containers/platform-details/#limits). Logging, metrics collection, and
-networking are automatically set up on each container.
+Once a particular container instance is running however (instances are defined with `MY_CONTAINER.get("unique-session-id")` ),
+any future requests while the container is alive will be routed to the initial location. However, if the container instance restarts,
+future requests could be routed to a different location.
+
+Note that Workers are not necessarily co-located with their associated Containers.
+
+An Example:
+
+- A user deploys a Container. Cloudflare automatically readies instances across its Network.
+- A request is made from a client in Bariloche, Argentia. It reaches the Worker in
+  Cloudflare's location in Neuquen, Argentina.
+- This Worker request calls `MY_CONTAINER.get("session-1337")` which brings up a Durable
+  Object, which then calls `this.ctx.container.start`.
+- This requests the nearest free Container instance.
+- Cloudflare recognizes that an instance is free in Buenos Aires, Argentina, and
+  starts it there.
+- A different user needs to route to the same container. This user's request reaches
+  the Worker running in Cloudflare's location in San Diego.
+- The Worker again calls `MY_CONTAINER.get("session-1337")`.
+- If the initial container instance is still running, the request is routed to the location
+  in Buenos Aires. If the initial container has gone to sleep, Cloudflare will once
+  again try to find the nearest "free" instance of the Container, likely
+  one in North America, and start an instance there.
 
 ## Life of a Container Request
 
@@ -62,3 +88,41 @@ which will allow container instances to always run in the same location as their
 Because all Container requests are passed through a Worker, end-users cannot make TCP or
 UDP requests to a Container instance. If you have a use case that requires inbound TCP
 or UDP from an end-user, please [let us know](https://forms.gle/AGSq54VvUje6kmKu8).
+
+### Cold starts
+
+A cold start is when a container instance is started from a completely stopped state.
+
+If you call `env.MY_CONTAINER.get(id)` with a completely novel ID and launch
+this instance for the first time, it will result in a cold start.
+
+This will start the container image from its entrypoint for the first time. Depending
+on what this entrypoint does, it will take a variable amount of time to start.
+
+Container cold starts can often be the 2-3 second range, but this is dependent
+on image size and code execution time, among other factors.
+
+Cloudflare will automatically pre-fetch images and pre-warm instances across its network as you scale.
+However, because there are a finite number pre-warmed locations, some container instances may be started in
+locations that are farther away from the end-user. This is done to ensure that the container instance starts quickly.
+
+You are only charged for actively running instances and not for any unused pre-warmed images.
+
+### After a request
+
+Cloudflare will not actively shut off a container instance after a specific amount of
+time. If you do not set `sleepAfter` on your Container class, or stop the instance
+manually, it will continue to run unless its host server is restarted. This
+happens on an irregular cadence, but frequently enough where Cloudflare does not
+guarantee that any instance will run for any set period of time.
+
+When a container instance is going to be shut down, it is sent a `SIGTERM` signal,
+and then a `SIGKILL` signal after 15 minutes. You should perform any necessary
+cleanup to ensure a graceful shutdown in this time. The container instance
+will be rebooted elsewhere shortly after this.
+
+All disk is ephemeral. When a Container instance goes to sleep, the next time
+it is started, it will have a fresh disk as defined by its container image.
+
+Persistent disk is something the Cloudflare team is exploring in the future, but
+is not slated for the near term.

src/content/docs/containers/platform-details/environment-variables.mdx

@@ -36,3 +36,4 @@ class MyContainer extends Container {
 :::note
 If you supply environment variables with the same names, supplied values will override predefined values.
 :::
+More details about defining environment variables and secrets can be found in [this example](/containers/examples/env-vars-and-secrets).