scaling tutorial

jordanstephens · jordanstephens · commit a93f4862aebf · 2024-12-13T14:00:16.000-08:00
diff --git a/docs/concepts/deployment-modes.md b/docs/concepts/deployment-modes.md
@@ -19,7 +19,7 @@ Defang provides three deployment modes: development, staging, and production. Th
 | Build Resources | Builds will be run with 2x vCPUs | Builds will be run with 2x vCPUs | Builds will be run with 4x vCPUs |
 | Databases | Defang will provision resources optimized for burstable memory | | Defang will provision resources optimized for production |
 | Static Resources | | | Defang will provision a CDN |
-| Deployment | Previous deployments will be spun down before new deployments are spun up. | | Rolling updates will be used to deploy new versions. Defang will gradually replace services while maintaining at least the original number of replicas. |
+| Deployment | Previous deployments will be spun down before new deployments are spun up. | | Rolling updates will be used to deploy new versions. Defang will gradually replace services while maintaining at least [the original number of replicas](/docs/tutorials/scaling-your-services). |
 | Logging | Logs retained for 1 day to save costs. | | Logs retained for 30 days for compliance. |
 | Networking | | | Defang will provision a NAT gateway. |
 | DNS | Defang will provision shorter TTLs | | Defang will provision longer TTLs |
diff --git a/docs/concepts/resources.md b/docs/concepts/resources.md
@@ -4,9 +4,9 @@ description: Customize the resources your Defang services use.
 sidebar_position: 350
 ---
 
-# Resources
+# Run-time Resources
 
-You can configure the resources available to your Defang services as required. You can configure the CPU, memory, and disk space allocated to your services as well as the number of replicas and whether or not your services requires access to GPUs.
+You can configure the resources available to your Defang services as required. You can configure the CPU, and memory allocated to your services as well as the number of replicas and whether or not your services requires access to GPUs.
 
 ## Examples
 
@@ -46,3 +46,29 @@ const service = new defang.DefangService("gpu-service", {
 If you require access to GPUs, you can specify this in the `deploy.resources.reservations.devices[0].capabilities` section of your service as in the examples above. You can learn more about this in the [Docker-Compose documentation](https://docs.docker.com/compose/gpu-support/). This is the only supported value in the `deploy.resources.reservations.devices` section.
 :::
 
+# Build-time Resources
+
+You can configure the memory requirements and disk space requirements for your image builds by using the `shm_size` property of your service's [`build` specification](https://github.com/compose-spec/compose-spec/blob/main/build.md).
+
+For example,
+
+```yaml
+services:
+  my_service:
+    build:
+      context: .
+      dockerfile: Dockerfile
+      shm_size: 2G
+```
+
+:::info
+Defang uses `shm_size` to configure both the memory and disk space available to your build process.
+:::
+
+The default `shm_size` values for each platform are as follows. More or less may be specified.
+
+| Platform      | `shm_size` Minimum |
+|---------------|--------------------|
+| AWS           | 16G                |
+| Digital Ocean | 8G                 |
+| GCP           | 16G                |
diff --git a/docs/faq/questions.md b/docs/faq/questions.md
@@ -45,15 +45,15 @@ import {Button, ButtonGroup, FormGroup, FormLabel} from "@mui/material"
 
 ### Does Defang support auto-scaling?
 
-- No. Defang does not currently support auto-scaling. However, you can manually scale your services by changing the number of replicas in your `compose.yaml` file and running `defang compose up`.
+- No. Defang does not currently support auto-scaling. However, you can check out the [Scaling Your Services](/docs/tutorials/scaling-your-services) tutorial, to see how you can scale your services manually with Defang.
 
 ### Can I cancel a deployment once it has started?
 
 - No. Once a deployment has started, it cannot be canceled. However, you can always deploy a new version of your app which will replace the current deployment.
 
 ### Will deploying a new version of my app cause downtime?
 
-- If you have deployed your application with the `--mode=production` flag, Defang will use the _production_ deployment mode. This mode will provision your app with multiple replicas and will perform a rolling update to ensure zero downtime. If you use another deployment mode, you may experience downtime during the deployment, as Defang will not provision multiple replicas to save cost. See the [Deployment Modes](/docs/concepts/deployment-modes) documentation for more information.
+- If you have deployed your application with the `--mode=production` flag, Defang will use the _production_ deployment mode. This mode will perform a rolling update to ensure zero downtime. If you use another deployment mode, you may experience downtime during the deployment, as Defang will not provision multiple replicas to save cost. See the [Deployment Modes](/docs/concepts/deployment-modes) documentation for more information.
 
 ### Can I deploy multiple services at once?
 
diff --git a/docs/faq/warnings-errors.md b/docs/faq/warnings-errors.md
@@ -4,7 +4,7 @@ title: Common Error Messages
 description: Common warnings and error messages, and their meanings.
 ---
 
-Here are the meanings of common [warning](#warnings) and [error](#errors) messages you may encounter in the Defang CLI. 
+Here are the meanings of common [warning](#warnings) and [error](#errors) messages you may encounter in the Defang CLI.
 
 ## Warnings
 
@@ -122,12 +122,4 @@ services:
 
 The image build might fail if the build process uses too much memory. The first thing to try is to limit the size of your project by excluding unnecessary files: the easiest way is to create a `.dockerignore` file that excludes irrelevatn files. Note that Defang will use a default `.dockerignore` file if you don't have one, but that default might not work for some projects and it's always better to make a `.dockerignore` file specific to your project.
 
-If that doesn't work, you can try to increase the memory available to the build process by adding a field `shm_size` to the `build` section in your `compose.yaml` file:
-
-```yaml
-services:
-  service1:
-    build:
-      context: .
-      shm_size: 16g
-```
+If that doesn't work, see our [Resources](/docs/concepts/resources#build-time-resources) documentation for more information on how to configure the memory requirements and disk space requirements for your image builds.
diff --git a/docs/tutorials/monitoring-your-services.md b/docs/tutorials/monitoring-your-services.md
@@ -6,7 +6,7 @@ description: How to monitor services deployed with Defang
 
 # Monitoring Your Services
 
-This page will show you how to monitor your service status and logs in Defang.
+This tutorial will show you how to monitor your service status and logs in Defang.
 
 ## Status
 
@@ -18,7 +18,7 @@ When deploying to your own cloud, the primary way to monitor your services is th
 
 When deploying to Playground, your service's logs may be viewed in the [Defang Portal](https://portal.defang.dev).
 
-By default when deploying, including to your own cloud, all output (stdout and stderr) from your app is logged and accessible via the [Defang CLI](/docs/getting-started#install-the-defang-cli). You can view these logs in real-time or for a time in the past. You can view logs for all your services, one service, or even one specific deployment of a service. 
+By default when deploying, including to your own cloud, all output (stdout and stderr) from your app is logged and accessible via the [Defang CLI](/docs/getting-started#install-the-defang-cli). You can view these logs in real-time or for a time in the past. You can view logs for all your services, one service, or even one specific deployment of a service.
 
 ### Tailing Live Logs For All Services
 
diff --git a/docs/tutorials/scaling-your-services.mdx b/docs/tutorials/scaling-your-services.mdx
@@ -0,0 +1,59 @@
+---
+sidebar_position: 550
+title: Scaling Your Services
+description: How to scale services deployed with Defang
+---
+
+# Scaling Your Services
+
+This tutorial will show you how to scale your services with Defang.
+
+There are two primary ways to scale a service. The first way is to increase the resources allocated to a service. For example, giving a service more CPUs or memory. The second way is to deploy multiple instances of a service. This is called scaling with replicas. Defang makes it easy to do both.
+
+The _Compose Specification_, which is used by defang, includes a [`deploy` section](https://github.com/compose-spec/compose-spec/blob/main/deploy.md) which allows you to configure the deployment configuration for a service. This includes your service's resource requirements and the number of replicas of a service should be deployed.
+
+## Scaling Resource Reservations
+
+In order to scale a service's resource reservations, you will need to update the `deploy` section associated with your service in your application's `compose.yaml` file.
+
+Use the [`resources`](https://github.com/compose-spec/compose-spec/blob/main/deploy.md#resources) section to specify the resource reservation requirements. These are the minimum resources which must be available for the platform to provision your service. You may end up with more resources than you requested, but you will never be allocated less.
+
+For example, if my app needs 2 CPUs and 512MB of memory, I would update the `compose.yaml` file like this:
+
+```yaml
+services:
+  my_service:
+    image: my_app:latest
+    deploy:
+      resources:
+        reservations:
+          cpus: '2'
+          memory: '512M'
+```
+
+The minimum resources which can be reserved:
+
+| Resource | Minimum |
+|----------|---------|
+| CPUs     | 0.5     |
+| Memory   | 512M    |
+
+:::info
+Note that the `memory` field must be specified as a ["byte value string"](https://github.com/compose-spec/compose-spec/blob/main/11-extension.md#specifying-byte-values) using the `{amount}{byte unit}` format. The supported units are `b` (bytes), `k` or `kb` (kilo bytes), `m` or `mb` (mega bytes) and `g` or `gb` (giga bytes).
+:::
+
+## Scaling with Replicas
+
+In order to scale a service's replica count, you will need to update the `deploy` section associated with your service in your application's `compose.yaml` file.
+
+Use the [`replicas`](https://github.com/compose-spec/compose-spec/blob/main/deploy.md#replicas) section to specify the number of containers which should be running at any given time.
+
+For example, if I want to run 3 instances of my app, I would update the `compose.yaml` file like this:
+
+```yaml
+services:
+  my_service:
+    image: my_app:latest
+    deploy:
+      replicas: 3
+```
diff --git a/docs/tutorials/updating-your-services.md b/docs/tutorials/updating-your-services.md
@@ -6,7 +6,7 @@ description: How to update services deployed with Defang
 
 # Updating Your Services
 
-This page will show you how to update your services in Defang.
+This tutorial will show you how to update your services in Defang.
 
 ## Updating a Service
 
