From aca36417a767b3677b16d187d8c5191361e480cf Mon Sep 17 00:00:00 2001
From: andie787 <4andie@gmail.com>
Date: Tue, 13 Aug 2024 16:48:35 -0400
Subject: [PATCH] start changes to autostart docs
---
apps/fine-tune-apps.html.markerb | 2 +-
launch/autostart-stop.html.markerb | 126 ------------------
launch/autostop-autostart.html.markerb | 101 ++++++++++++++
partials/_apps_nav.html.erb | 2 +-
partials/_firecracker_nav.html.erb | 1 +
reference/configuration.html.markerb | 8 +-
.../fly-proxy-autostop-autostart.html.markerb | 53 ++++++++
reference/fly-proxy.html.markerb | 2 +-
8 files changed, 162 insertions(+), 133 deletions(-)
delete mode 100644 launch/autostart-stop.html.markerb
create mode 100644 launch/autostop-autostart.html.markerb
create mode 100644 reference/fly-proxy-autostop-autostart.html.markerb
diff --git a/apps/fine-tune-apps.html.markerb b/apps/fine-tune-apps.html.markerb
index cfeb3140b1..6343890283 100644
--- a/apps/fine-tune-apps.html.markerb
+++ b/apps/fine-tune-apps.html.markerb
@@ -1,5 +1,5 @@
---
-title: Tips to fine-tune and (not) benchmark your app on Fly.io
+title: Tips to fine-tune your app on Fly.io
layout: docs
nav: apps
redirect_from: /docs/reference/fine-tune-apps/
diff --git a/launch/autostart-stop.html.markerb b/launch/autostart-stop.html.markerb
deleted file mode 100644
index d482a29faa..0000000000
--- a/launch/autostart-stop.html.markerb
+++ /dev/null
@@ -1,126 +0,0 @@
----
-title: Automatically stop and start Machines
-layout: docs
-nav: apps
-redirect_from: /docs/apps/autostart-stop/
----
-
-
-
-
-
-Fly Machines are fast to start and stop, and you don't pay for their CPU and RAM when they're in a `stopped` or `suspended` state. For Fly Apps with a service configured, [Fly Proxy](/docs/reference/fly-proxy) can automatically start and stop or suspend existing Machines based on incoming requests, so that your app can meet demand without keeping extra Machines running. You can also set a minimum number of machines to keep running at all times in your primary region.
-
-The autostop/autostart feature also works well for apps that [shut down automatically when idle](#stop-a-machine-by-terminating-its-main-process). The Fly Proxy can still restart your app when there's traffic.
-
-## Configure automatic start and stop
-
-The autostop/autostart settings apply per service, and you set them within the services configured in the `fly.toml` file. See the [[[services]]](/docs/reference/configuration/#the-services-sections) or [[http_service]](/docs/reference/configuration/#the-http_service-section) docs for details.
-
-Example configuration:
-
-```toml
-...
-[[services]]
- internal_port = 8080
- protocol = "tcp"
- auto_stop_machines = "stop"
- auto_start_machines = true
- min_machines_running = 0
-...
-```
-
-For the preceding example, Fly Proxy will automatically stop Machines when the app has excess capacity and start them again when needed. The app will eventually scale all the way down to zero running Machines if there's no traffic.
-
-Autostop/autostart setting descriptions:
-
-* `auto_stop_machines`: The action, if any, that Fly Proxy should take when the app is idle for several minutes. Options are `"off"`, `"stop"`, or `"suspend"`.
-* `auto_start_machines`: Whether Fly Proxy should automatically start Machines based on requests and capacity.
-* `min_machines_running`: The minimum number of Machines to keep running in the primary region when `auto_stop_machines` is set to `"stop"` or `"suspend"`.
-
-Concurrency limits configured for services also affect [how automatic starts and stops work](#how-it-works).
-
-### Default settings
-
-When you create an app using the `fly launch` command, the default settings in `fly.toml` are:
-
-```toml
-...
-[http_service]
- internal_port = 8080
- force_https = true
- auto_stop_machines = "stop"
- auto_start_machines = true
- min_machines_running = 0
-...
-```
-
-For apps that don't explicitly specify any autostop/autostart settings in `fly.toml`, the Fly Proxy will automatically start stopped Machines when needed, but won't automatically stop or suspend them.
-
-### Recommended settings
-
-If your app already [exits when idle](#stop-a-machine-by-terminating-its-main-process), then you can set `auto_start_machines = true` and `auto_stop_machines = "off"` to have Fly Proxy automatically restart the Machines stopped by your app.
-
-If your app doesn't exit when idle, then we recommend setting `auto_stop_machines` and `auto_start_machines` so that they are both enabled or both disabled, to avoid having Machines that either never start or never stop. For example, if `auto_start_machines = false` and `auto_stop_machines = "stop"`, then Fly Proxy automatically stops your Machines when there's low traffic but doesn't start them again. When all or most of your Machines stop, requests to your app could start failing.
-
-To keep one or more Machines running all the time in your primary region, set `min_machines_running` to `1` or higher. `min_machines_running` has no effect unless you set `auto_stop_machines` to `"stop"` or `"suspend"`.
-
-`min_machines_running` only applies to Machines running in your primary region. If `min_machines_running = 1` and there's no traffic to your app, then Fly Proxy will stop Machines until eventually there is only one Machine running in your primary region.
-
-There's no "maximum machines running" setting, because the maximum number of Machines is the total number of Machines you've created for your app.
-
-## How it works
-
-The Fly Proxy runs a process to automatically start and stop or suspend existing Fly Machines every few minutes.
-
-
-The autostop/autostart feature only works on existing Machines and never creates or destroys Machines for you. The maximum number of running Machines is the number of Machines you've created for your app using `fly scale count` or `fly machine clone`. Learn more about [scaling the number of Machines](/docs/apps/scale-count/).
-
-
-### When Fly Proxy stops or suspends Machines
-
-When `auto_stop_machines` is set to `"stop"` or `"suspend"` in your `fly.toml`, the proxy looks at Machines running in a single region and uses the concurrency [`soft_limit` setting](/docs/reference/configuration/#the-http_service-section) for each Machine to determine if there's excess capacity. If the proxy decides there's excess capacity, it stops or suspends exactly one Machine. The proxy repeats this process every few minutes, stopping or suspending only one Machine per region, if needed, each time.
-
-If you have the [`kill_signal` and `kill_timeout` options](/docs/reference/configuration/#runtime-options) configured in your `fly.toml` file, then Fly Proxy uses those settings when it stops a Machine.
-
-Fly Proxy determines excess capacity per region as follows:
-
-* If there's more than one Machine in the region:
- * the proxy determines how many running Machines are over their `soft_limit` setting and then calculates excess capacity: `excess capacity = num of machines - (num machines over soft limit + 1)`
- * if excess capacity is 1 or greater, then the proxy stops or suspends one Machine
-* If there's only one Machine in the region:
- * the proxy checks if the Machine has any traffic
- * if the Machine has no traffic (a load of 0), then the proxy stops or suspends the Machine
-
-### When Fly Proxy starts Machines
-
-When `auto_start_machines = true` in your `fly.toml`, the Fly Proxy restarts a Machine in the nearest region when required.
-
-Fly Proxy determines when to start a Machine as follows:
-
-* The proxy waits for a request to your app.
-* If all the running Machines are above their `soft_limit` setting, then the proxy starts a stopped or suspended Machine in the nearest region (if there are any stopped or suspended Machines).
-* The proxy routes the request to the newly started Machine.
-
-## When to use the autostop/autostart feature
-
-If your app has highly variable request workloads, then you can use `auto_stop_machines` and `auto_start_machines` to manage your Fly Machines as demand decreases and increases. This could reduce costs, because you'll never have to run excess Machines to handle peak load; you'll only run, and get charged for, the number of Machines that you need.
-
-The difference between this feature and what's typical in autoscaling, is that it doesn't create new Machines up to a specified maximum. It automatically starts only existing Machines. For example, if you want to have a maximum of 10 Machines available to service requests, then you need to create 10 Machines for your app.
-
-If you need all your app's Machines to run continuously, then you can set `auto_stop_machines` to `"off"` and `auto_start_machines` to `false`.
-
-If you only need a certain number of your app's Machines to run continuously, then you can set `auto_stop_machines` to `"suspend"` or `"stop"` and `min_machines_running` to `1` or higher. Note that `min_machines_running` only applies to your app's primary region.
-
-## Stop a Machine by terminating its main process
-
-Setting your app to automatically stop or suspend Machines when there's excess capacity using `auto_stop_machines` can be a substitute for when your app doesn't shut itself down automatically after a period of inactivity. If you want a custom shutdown process for your app, then you can code your app to exit when idle.
-
-Here are some examples:
-
-* [Shutting Down a Phoenix App When Idle](https://fly.io/phoenix-files/shut-down-idle-phoenix-app/): a post by Chris McCord on adding a task to an Elixir app's supervision tree that shuts down the Erlang runtime when there are no active connections.
-* For Rails apps, the `dockerfile-rails` generator provides a [--max-idle](https://github.com/rubys/dockerfile-rails#addremove-a-feature+external) option that exits after _n_ seconds of inactivity.
-* [A Tired Proxy in Go](https://github.com/superfly/tired-proxy+external) used in [Building an In-Browser IDE the Hard Way](https://fly.io/blog/remote-ide-machines/). [There's a community fork with more recent updates](https://community.fly.io/t/improved-tired-proxy-for-use-with-fly-machines/10584).
-* A minimal demo app in TypeScript/Remix: [code](https://github.com/fly-apps/autoscale-to-zero-demo+external) & [demo](https://autoscale-to-zero-demo.fly.dev/+external).
-
-Fly Postgres also [supports scaling to zero](https://community.fly.io/t/scale-to-zero-postgres-for-hobby-projects/12212).
diff --git a/launch/autostop-autostart.html.markerb b/launch/autostop-autostart.html.markerb
new file mode 100644
index 0000000000..dcc253b955
--- /dev/null
+++ b/launch/autostop-autostart.html.markerb
@@ -0,0 +1,101 @@
+---
+title: Autostop/autostart Machines
+layout: docs
+nav: apps
+redirect_from:
+ - /docs/apps/autostart-stop/
+ - /docs/launch/autostart-stop/
+---
+
+For Fly Apps with a service configured, [Fly Proxy](/docs/reference/fly-proxy/) can automatically start and stop or suspend existing Machines based on incoming requests, so that your app can meet demand without keeping extra Machines running. Fly Machines are fast to start and stop, and you don't pay for their CPU and RAM when they're in a `stopped` or `suspended` state.
+
+Learn more about exactly how [Fly Proxy autostops and autostarts Machines](/docs/reference/fly-proxy-autostop-autostart/).
+
+## When to use autostop/autostart
+
+You can reduce resource usage and costs by using autostop/autostart to manage your Fly Machines as demand decreases and increases. You'll never have to run excess Machines to handle peak load; you'll only run, and get charged for, the number of Machines that you need. Autostart/autostop works well for apps with highly variable workloads, for smaller apps with low or sporadic traffic, and for most apps that aren't accepting requests continuously. If you need to, you can keep one or more Machines running in your primary region.
+
+## Configure autostop/autostart
+
+The autostop/autostart settings apply per service in an app's `fly.toml` file. See the [[[services]]](/docs/reference/configuration/#the-services-sections) or [[http_service]](/docs/reference/configuration/#the-http_service-section) docs for details about services.
+
+Autostop/autostart settings:
+
+* **`auto_stop_machines`:** The action, if any, that Fly Proxy should take when the app is idle for several minutes. Options are `"off"`, `"stop"`, or `"suspend"`. If `"off"`, Fly Proxy will never stop Machines. If `"stop"`, Fly Proxy stops Machines when the app has excess capacity. If `"suspend"`, Fly Proxy suspends Machines (if possible) when the app has excess capacity. Starting a Machine from a `suspended` state is faster than starting a Machine from a `stopped` state, but there are [some caveats](https://community.fly.io/t/autosuspend-is-here-machine-suspension-is-enabled-everywhere/20942).
+* **`auto_start_machines`:** Whether Fly Proxy should automatically start Machines based on requests and capacity.
+* **`min_machines_running`:** The minimum number of Machines to keep running in the primary region when `auto_stop_machines` is set to `"stop"` or `"suspend"`.
+
+Example configuration:
+
+```toml
+...
+[[services]]
+ internal_port = 8080
+ protocol = "tcp"
+ auto_stop_machines = "stop"
+ auto_start_machines = true
+ min_machines_running = 1
+...
+```
+
+In the preceding example, Fly Proxy will automatically stop Machines when the app has excess capacity and start them again when needed based on traffic to the app. The app will eventually scale down to one running Machine in the primary region if there's no traffic.
+
+Concurrency limits configured for services in the `fly.toml` file also affect [how automatic starts and stops work](#how-it-works).
+
+## Recommendations for autostop/autostart configuration
+
+In general, unless your app shuts itself down when idle, we recommend setting `auto_stop_machines` and `auto_start_machines` so that they are both enabled or both disabled, to avoid having Machines that either never start or never stop. For example, if `auto_start_machines = false` and `auto_stop_machines = "stop"`, then Fly Proxy automatically stops your Machines when there's low traffic but doesn't start them again. When all or most of your Machines stop, requests to your app could start failing.
+
+### Minimum number of Machines running
+
+To keep one or more Machines running all the time in your primary region, set `min_machines_running` to `1` or higher. If `min_machines_running = 1` and there's no traffic to your app, then Fly Proxy will stop Machines until eventually there is only one Machine running in your primary region. `min_machines_running` has no effect unless you set `auto_stop_machines` to `"stop"` or `"suspend"`.
+
+### Maximum number of Machines running
+
+There's no "maximum machines running" setting, because the maximum number of Machines is the total number of Machines in your app.
+
+The autostop/autostart feature never creates or destroys Machines for you. The maximum number of running Machines is the number of Machines created for your app on launch, or using `fly scale count` or `fly machine clone`. For example, if you want to have a maximum of 10 Machines available to service requests, then you need to create 10 Machines for your app. Learn more about [scaling the number of Machines](/docs/apps/scale-count/).
+
+### Keep all Machines running continuously
+
+If you need all your app's Machines to run continuously, then you can set `auto_stop_machines` to `"off"` and `auto_start_machines` to `false`.
+
+If you only need a certain number of your app's Machines to run continuously, then you can set `auto_stop_machines` to `"suspend"` or `"stop"` and `min_machines_running` to `1` or higher. Note that `min_machines_running` only applies to your app's primary region.
+
+### Apps that shut down when idle
+
+Setting your app to automatically stop or suspend Machines when there's excess capacity using `auto_stop_machines` can be a substitute for when your app doesn't shut itself down automatically after a period of inactivity. If your app already shuts down when idle, then you can set `auto_start_machines = true` and `auto_stop_machines = "off"` to have Fly Proxy automatically restart the Machines stopped by your app.
+
+If you want a custom shutdown process for your app, then you can code your app to exit when idle.
+
+Here are some examples:
+
+* [Shutting Down a Phoenix App When Idle](https://fly.io/phoenix-files/shut-down-idle-phoenix-app/): a post by Chris McCord on adding a task to an Elixir app's supervision tree that shuts down the Erlang runtime when there are no active connections.
+* For Rails apps, the `dockerfile-rails` generator provides a [--max-idle](https://github.com/rubys/dockerfile-rails#addremove-a-feature+external) option that exits after _n_ seconds of inactivity.
+* [A Tired Proxy in Go](https://github.com/superfly/tired-proxy+external) used in [Building an In-Browser IDE the Hard Way](https://fly.io/blog/remote-ide-machines/). [There's a community fork with more recent updates](https://community.fly.io/t/improved-tired-proxy-for-use-with-fly-machines/10584).
+* A minimal demo app in TypeScript/Remix: [code](https://github.com/fly-apps/autoscale-to-zero-demo+external) & [demo](https://autoscale-to-zero-demo.fly.dev/+external).
+
+Fly Postgres also [supports scaling to zero](https://community.fly.io/t/scale-to-zero-postgres-for-hobby-projects/12212).
+
+## Default settings
+
+The defaults differ for new apps created with `fly launch` and for apps with no settings configured for autostop/autostart.
+
+### Apps created with `fly launch`
+
+When you create a new app using the `fly launch` command, the default settings in `fly.toml` are:
+
+```toml
+...
+[http_service]
+ internal_port = 8080
+ force_https = true
+ auto_stop_machines = "stop"
+ auto_start_machines = true
+ min_machines_running = 0
+...
+```
+
+### Apps with no autostop/autostart settings
+
+For apps that don't explicitly specify any autostop/autostart settings in `fly.toml`, the Fly Proxy will automatically start stopped Machines when needed, but won't automatically stop or suspend them.
diff --git a/partials/_apps_nav.html.erb b/partials/_apps_nav.html.erb
index 0ef1835b65..73b656fecf 100644
--- a/partials/_apps_nav.html.erb
+++ b/partials/_apps_nav.html.erb
@@ -23,7 +23,7 @@
{ text: "Deploy an app", path: "/docs/launch/deploy/" },
{ text: "Scale Machine CPU and RAM", path: "/docs/launch/scale-machine/" },
{ text: "Scale the number of Machines", path: "/docs/launch/scale-count/" },
- { text: "Autostop/autostart Machines", path: "/docs/launch/autostart-stop/" },
+ { text: "Autostop/autostart Machines", path: "/docs/launch/autostop-autostart/" },
{ text: "Autoscale based on metrics", path: "/docs/launch/autoscale-by-metric/" },
{ text: "Add volume storage", path: "/docs/launch/volume-storage/" },
{ text: "Use process groups", path: "/docs/launch/processes/" },
diff --git a/partials/_firecracker_nav.html.erb b/partials/_firecracker_nav.html.erb
index b60cff3ab6..f5f1b8b4f8 100644
--- a/partials/_firecracker_nav.html.erb
+++ b/partials/_firecracker_nav.html.erb
@@ -177,6 +177,7 @@
{ text: "Machine migration", path: "/docs/reference/machine-migration/" },
{ text: "Multiple Processes in Apps", path: "/docs/app-guides/multiple-processes/" },
{ text: "Fly Proxy", path: "/docs/reference/fly-proxy/" },
+ { text: "Fly Proxy autostop/autostart", path: "/docs/reference/fly-proxy-autostop-autostart/" },
{ text: "Regions", path: "/docs/reference/regions/" }
]
},
diff --git a/reference/configuration.html.markerb b/reference/configuration.html.markerb
index 6e63e8d697..b25d160bff 100644
--- a/reference/configuration.html.markerb
+++ b/reference/configuration.html.markerb
@@ -287,9 +287,9 @@ As with the more verbose [`[[services]]`](#the-services-sections), you can speci
* `processes`: For apps with multiple processes. The process group that this service belongs to. Define process groups in the [processes](#the-processes-section) section.
* `internal_port`: The port this service (and application) will use to communicate with clients. The default is 8080. We recommend applications use the default.
* `force_https`: A Boolean which determines whether to enforce HTTP to HTTPS redirects.
-* `auto_stop_machines`: Whether to automatically stop or suspend an application's Machines when there's excess capacity, per region. Options are `"off"`, `"stop"`, and `"suspend"`. If there's only one Machine in a region, then the Machine is stopped or suspended if it has no traffic. The Fly Proxy runs a process to automatically stop Machines every few minutes. The default if not set is `"off"`.
+* `auto_stop_machines`: The action, if any, that Fly Proxy should take when the app is idle for several minutes. Options are `"off"`, `"stop"`, or `"suspend"`. If `"off"`, Fly Proxy will never stop Machines. If `"stop"`, Fly Proxy stops Machines when the app has excess capacity. If `"suspend"`, Fly Proxy suspends Machines (if possible) when the app has excess capacity. Starting a Machine from a `suspended` state is faster than starting a Machine from a `stopped` state, but there are [some caveats](https://community.fly.io/t/autosuspend-is-here-machine-suspension-is-enabled-everywhere/20942). If there's only one Machine in a region, then the Machine is stopped or suspended if it has no traffic. The Fly Proxy runs a process to automatically stop Machines every few minutes. The default if not set is `"off"`.
* `auto_start_machines`: Whether to automatically start an application's Machines when a new request is made to the application and there's no excess capacity, per region. If there's only one Machine in a region, then it's started whenever a request is made to the application. The default if not set is `true`.
-* `min_machines_running`: The number of Machines to keep running, in the primary region only, when `auto_stop_machines` is `"stop"` or `"suspend"`.
+* `min_machines_running`: The number of Machines to keep running, in the primary region only, when `auto_stop_machines` is `"stop"` or `"suspend"`. The default if not set is `0`.
We recommend configuring `auto_stop_machines` and `auto_start_machines` so that they are both enabled or both disabled, to avoid having Machines that either never start or never stop. Learn more about [automatically starting and stopping Machines](/docs/launch/autostart-stop/), including how Fly Proxy determines excess capacity in a region using the `soft_limit` setting.
@@ -445,9 +445,9 @@ Settings:
* `processes`: For apps with multiple process groups, the process group or groups that this service belongs to. Define process groups in the [processes](#the-processes-section) section.
* `internal_port` : The port this service (and application) will use to communicate with clients. The default is 8080. We recommend applications use the default.
* `protocol` : The protocol that this service will use to communicate. Typically `tcp` for most applications, but can also be `udp`.
-* `auto_stop_machines`: Whether to automatically stop or suspend an application's Machines when there's excess capacity, per region. Options are `"off"`, `"stop"`, and `"suspend"`. If there's only one Machine in a region, then the Machine is stopped or suspended if it has no traffic. The Fly Proxy runs a process to automatically stop Machines every few minutes. The default if not set is `"off"`.
+* `auto_stop_machines`: The action, if any, that Fly Proxy should take when the app is idle for several minutes. Options are `"off"`, `"stop"`, or `"suspend"`. If `"off"`, Fly Proxy will never stop Machines. If `"stop"`, Fly Proxy stops Machines when the app has excess capacity. If `"suspend"`, Fly Proxy suspends Machines (if possible) when the app has excess capacity. Starting a Machine from a `suspended` state is faster than starting a Machine from a `stopped` state, but there are [some caveats](https://community.fly.io/t/autosuspend-is-here-machine-suspension-is-enabled-everywhere/20942). If there's only one Machine in a region, then the Machine is stopped or suspended if it has no traffic. The Fly Proxy runs a process to automatically stop Machines every few minutes. The default if not set is `"off"`.
* `auto_start_machines`: Whether to automatically start an application's Machines when a new request is made to the application and there's no excess capacity, per region. If there's only one Machine in a region, then it's started whenever a request is made to the application. The default if not set is `true`.
-* `min_machines_running`: The number of Machines to keep running, in the primary region only, when `auto_stop_machines` is `"stop"` or `"suspend"`.
+* `min_machines_running`: The number of Machines to keep running, in the primary region only, when `auto_stop_machines` is `"stop"` or `"suspend"`. The default if not set is `0`.
We recommend configuring `auto_stop_machines` and `auto_start_machines` so that they are both enabled or both disabled, to avoid having Machines that either never start or never stop. Learn more about [automatically starting and stopping Machines](/docs/launch/autostart-stop/), including how Fly Proxy determines excess capacity in a region using the `soft_limit` setting.
diff --git a/reference/fly-proxy-autostop-autostart.html.markerb b/reference/fly-proxy-autostop-autostart.html.markerb
new file mode 100644
index 0000000000..23503e1efd
--- /dev/null
+++ b/reference/fly-proxy-autostop-autostart.html.markerb
@@ -0,0 +1,53 @@
+---
+title: Fly Proxy autostop/autostart
+layout: docs
+nav: firecracker
+---
+
+
+
+
+
+For Fly Apps with a service configured, [Fly Proxy](/docs/reference/fly-proxy) can automatically stop (or suspend) and start existing Machines based on incoming requests, so that your app can meet demand without keeping extra Machines running. Fly Machines are fast to start and stop, and you don't pay for their CPU and RAM when they're in a `stopped` or `suspended` state. You can also set a minimum number of machines to keep running at all times in your primary region.
+
+You can also use the autostop/autostart with apps that [shut down automatically when idle](#stop-a-machine-by-terminating-its-main-process). The Fly Proxy can still restart your app when there's traffic.
+
+Learn how to [configure autostop/autostart](/docs/launch/autostop-autostart/).
+
+## How Fly Proxy autostops and autostarts Machines
+
+The Fly Proxy runs a process to determine whether an app has excess capacity every few minutes.
+
+
+The autostop/autostart feature only works on existing Machines and never creates or destroys Machines for you. The maximum number of running Machines is the number of Machines you've created for your app using `fly scale count` or `fly machine clone`. Learn more about [scaling the number of Machines](/docs/apps/scale-count/).
+
+
+### Fly Proxy process to stop or suspend Machines
+
+When `auto_stop_machines` is set to `"stop"` or `"suspend"` in your `fly.toml`, the proxy looks at Machines running in a single region and uses the concurrency [`soft_limit` setting](/docs/reference/configuration/#the-http_service-section) for each Machine to determine if there's excess capacity. If the proxy decides there's excess capacity, it stops or suspends exactly one Machine. The proxy repeats this process every few minutes, stopping or suspending only one Machine per region, if needed, each time.
+
+If you have the [`kill_signal` and `kill_timeout` options](/docs/reference/configuration/#runtime-options) configured in your `fly.toml` file, then Fly Proxy uses those settings when it stops a Machine.
+
+Fly Proxy determines excess capacity per region as follows:
+
+* If there's more than one Machine in the region:
+ * the proxy determines how many running Machines are over their `soft_limit` setting and then calculates excess capacity: `excess capacity = num of machines - (num machines over soft limit + 1)`
+ * if excess capacity is 1 or greater, then the proxy stops or suspends one Machine
+* If there's only one Machine in the region:
+ * the proxy checks if the Machine has any traffic
+ * if the Machine has no traffic (a load of 0), then the proxy stops or suspends the Machine
+
+### Fly Proxy process to start Machines
+
+When `auto_start_machines = true` in your `fly.toml`, the Fly Proxy restarts a Machine in the nearest region when required.
+
+Fly Proxy determines when to start a Machine as follows:
+
+* The proxy waits for a request to your app.
+* If all the running Machines are above their `soft_limit` setting, then the proxy starts a stopped or suspended Machine in the nearest region (if there are any stopped or suspended Machines).
+* The proxy routes the request to the newly started Machine.
+
+## Related topics
+
+- [Fly Proxy features](/docs/reference/fly-proxy)
+- [Configure autostop/autostart for Fly Launch apps](/docs/launch/autostop-autostart/)
diff --git a/reference/fly-proxy.html.markerb b/reference/fly-proxy.html.markerb
index f2a21c6fb8..0f9db3e85c 100644
--- a/reference/fly-proxy.html.markerb
+++ b/reference/fly-proxy.html.markerb
@@ -51,7 +51,7 @@ Fly Proxy can start and stop existing Machines based on incoming requests, so th
Fly Proxy uses the same concurrency settings for autostart/autostop as for load balancing to determine when Machines have excess capacity and can be stopped.
-Learn more about [how autostart/autostop works and how to configure it](/docs/apps/autostart-stop/).
+Learn more about [how autostart/autostop works](/docs/reference/fly-proxy-autostop-autostart/) and [how to configure it](/docs/apps/autoststop-autostart/).
## Dynamic request routing with `fly-replay`
-