From 00c6865037db3d213a8e6c7a6176a8a965a21924 Mon Sep 17 00:00:00 2001 From: commit111 Date: Mon, 2 Dec 2024 10:24:53 -0800 Subject: [PATCH 01/22] categorize faq with headings --- docs/faq/faq2.md | 73 ++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 73 insertions(+) create mode 100644 docs/faq/faq2.md diff --git a/docs/faq/faq2.md b/docs/faq/faq2.md new file mode 100644 index 000000000..1e37005ea --- /dev/null +++ b/docs/faq/faq2.md @@ -0,0 +1,73 @@ +--- +sidebar_position: 600 +title: Frequently Asked Questions +description: Frequently asked questions about Defang. +--- +import {Button, ButtonGroup, FormGroup, FormLabel} from "@mui/material" + +# Frequently Asked Questions (FAQ) + +## Deployment and Infrastructure +### Which cloud/region is the app being deployed to? + +- In the [Defang Playground](../concepts/defang-playground.md), the app is deployed to AWS `us-west-2`. In the [Defang BYOC](../concepts/defang-byoc.md) model, the region is determined by your [Defang BYOC Provider](/docs/category/providers) settings. + +### Can I bring my own AWS or other cloud account? + +- Yes! Defang makes it easy to deploy your application to your own cloud account. Please check out the [Defang BYOC](../concepts/defang-byoc.md) documentation for more information. + +### On AWS, can I deploy to services such as EC2, EKS, or Lambda? + +- The current release includes support for containers only, deployed to ECS. We are still exploring how to support additional execution models such as VMs and functions-as-a-service. However, using our Pulumi provider, it is possible to combine Defang services with other native AWS resources. + +### Can I access AWS storage services such as S3 or database services such as RDS? How? + +- Yes! You can access AWS services in the AWS Dashboard as you normally would when you are [deploying to your AWS account](../providers/aws) using Defang. In fact, you can access whatever other resources exist in the cloud account you are using for [Defang BYOC](../concepts/defang-byoc.md). + +### Do you plan to support other clouds? + +- While we currently support [AWS](../concepts/defang-byoc#aws) for production and [DigitalOcean](../concepts/defang-byoc#digitalocean) in preview, we plan to support other clouds in future releases, such as [GCP](../providers/gcp.md) and [Azure](../providers/azure.md). + +## Deployment Process + +### Can I run production apps with Defang? + +- Yes! Defang makes it easy to deploy your app on production-ready infrastructure in your own cloud account. For example, you can deploy your app to AWS with `defang up --provider=aws --mode=production`. Check out your preferred cloud provider on [Defang BYOC](../concepts/defang-byoc.md). + +### Does Defang support blue/green deployments? + +- Defang does not currently support Blue/Green deploys, but it does support rolling updates with the `production` deployment mode. `defang up --mode=production`. + +### Does Defang support rolling deployments? + +- Yes! Defang supports rolling updates with the `production` deployment mode. `defang up --mode=production`. + +### 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. + +### Can I deploy multiple services at once? + +- Yes! You can deploy multiple services at once by defining them in a single compose.yaml file. When you run `defang compose up`, Defang will deploy all the services defined in the file at once. + +### Can I deploy a service that depends on another service? + +- Defang does not currently support service dependencies. All services will be deployed simultaneously. Defang will however run multiple healthchecks before marking a service as healthy and spinning down any previously deployed services when using the `production` deployment mode. + +## Troubleshooting + +### I'm having trouble running the binary on my Mac. What should I do? + +- MacOS users will need to allow the binary to run due to security settings: + 1. Attempt to run the binary. You'll see a security prompt preventing you from running it. + 2. Go to System Preferences > Privacy & Security > General. + 3. In the 'Allow applications downloaded from:' section, you should see a message about Defang being blocked. Click 'Open Anyway'. + 4. Alternatively, select the option "App Store and identified developers" to allow all applications from the App Store and identified developers to run. + +### I'm getting a warning/error. What does it mean? +- See the Common Warnings and Errors page. + From a66e751a52290946ab5fd83530f0a84a9c02c499 Mon Sep 17 00:00:00 2001 From: commit111 Date: Mon, 2 Dec 2024 10:25:23 -0800 Subject: [PATCH 02/22] add new warning/error messages section --- docs/faq/_category_.json | 9 +++ docs/faq/warnings-errors.md | 133 ++++++++++++++++++++++++++++++++++++ 2 files changed, 142 insertions(+) create mode 100644 docs/faq/_category_.json create mode 100644 docs/faq/warnings-errors.md diff --git a/docs/faq/_category_.json b/docs/faq/_category_.json new file mode 100644 index 000000000..dd0a2f94d --- /dev/null +++ b/docs/faq/_category_.json @@ -0,0 +1,9 @@ +{ + "label": "FAQ", + "position": 600, + "link": { + "type": "generated-index", + "description": "Wondering about something? Check out one of the guides below for additional support." + } + } + \ No newline at end of file diff --git a/docs/faq/warnings-errors.md b/docs/faq/warnings-errors.md new file mode 100644 index 000000000..d99cc5eb9 --- /dev/null +++ b/docs/faq/warnings-errors.md @@ -0,0 +1,133 @@ +--- +sidebar_position: 700 +title: Common Error Messages +description: Common warnings and error messages, and their meanings. +--- + +Here are meanings of common [warning](#warnings) and [error](#errors) messages you may encounter in the Defang CLI. + +## Warnings + +### "The folder is not empty. Files may be overwritten." +- This message is displayed when you run `defang generate` and the target folder is not empty. If you proceed, Defang will overwrite any existing files with the same name. If you want to keep the existing files, you should move them to a different folder before running `defang generate` or pick a different target folder. + +### "environment variable not found" +- This message is displayed when you run `defang compose up` and the Compose file references an environment variable that is not set. If you proceed, the environment variable will be empty in the container. If you want to set the environment variable, you should set it in the environment where you run `defang compose up`. + +### "Unsupported platform" +- This message is displayed when you run `defang compose up` and the Compose file references a platform that is not supported by Defang. Defang Beta only supports Linux operating systems. + +### "not logged in" +- This message is displayed when you run `defang compose config` but you are not logged in. The displayed configuration will be incomplete. If you want to see the complete configuration, you should log in first using `defang login`. + +### "No port mode was specified; assuming 'host'" +- This message is displayed when you run `defang compose up` and the Compose file declares a `port` that does not specify a port `mode`. By default, Defang will keep the port private. If you want to expose the port to the public internet, you should specify the `mode` as `ingress`: +``` +services: + service1: + … + ports: + - target: 80 + mode: ingress +``` + +### "Published ports are not supported in ingress mode; assuming 'host'" +- This message is displayed when you run `defang compose up` and the Compose file declares a `port` with `mode` set to `ingress` and `published` set to a port number. Defang does not support published ports in ingress mode. If you want to expose the port to the public internet, you should specify the `mode` as `ingress` and remove the `published` setting. + +### "TCP ingress is not supported; assuming HTTP" +- This message is displayed when you run `defang compose up` and the Compose file declares a `port` with `mode` set to `ingress` and `protocol` set to `tcp`. Defang does not support arbitrary TCP ingress and will assume the port is used for HTTP traffic. To silence the warning, remove the `protocol` setting. + +### "unsupported compose directive" +- This message is displayed when you run `defang compose up` and the Compose file declares a directive that is not supported by Defang. The deployment will continue, but the unsupported directive will be ignored, which may cause unexpected behavior. + +### "no reservations specified; using limits as reservations" +- This message is displayed when you run `defang compose up` and the Compose file declares a `resource` with `limits` but no `reservations`. Defang will use the `limits` as `reservations` to ensure the container has enough resources. Specify `reservations` if you want to silence the warning or reserve a different amount of resources: +``` +services: + service1: + … + deploy: + resources: + reservations: + cpus: 0.5 + memory: 512MB +``` + +### "ingress port without healthcheck defaults to GET / HTTP/1.1" +- This message is displayed when you run `defang compose up` and the Compose file declares an `ingress` with a `port` but no `healthcheck`. Defang will assume the default healthcheck of `GET / HTTP/1.1` to ensure the port is healthy. Specify a `healthcheck` if you want to silence the warning or use a different healthcheck: +``` +services: + service1: + … + deploy: + healthcheck: + test: ["CMD", "curl", "-f", "http://localhost:80/health"] +``` + +### "missing memory reservation; specify deploy.resources.reservations.memory to avoid out-of-memory errors" +- This message is displayed when you run `defang compose up` and the Compose file doesn't specify a `memory` reservation. If available, Defang will use the `memory` limit as the `memory` reservation. Specify a `memory` reservation if you want to silence the warning or reserve a different amount of memory: +``` +services: + service1: + … + deploy: + resources: + reservations: + memory: 512MB +``` + +### "The build context contains more than 10 files" +- This message is displayed when you run `defang compose up` and the Compose file declares a `build` with a `context` that contains more than 10 files. Ensure the context refers to the correct folder. Defang will use the `context` as is, but you may experience slow build times. If you want to speed up the build, you should reduce the number of files in the `context`. + +### "AWS provider was selected, but AWS environment variables are not set" +- This message is displayed when you run `defang compose up` with the `--provider=aws` but none of the AWS environment variables were set. If you proceed, the deployment might fail, unless you have defined defined `default` credentials in the AWS configuration files or are running on an AWS instance. + +### "Using Defang provider, but AWS environment variables were detected" +- This message is displayed when you run `defang compose up` with the `--provider=defang` but AWS environment variables were detected. The AWS environment variables will be ignored. + +## Errors + +### "Stack:… is in UPDATE_COMPLETE_CLEANUP_IN_PROGRESS state and cannot be updated" +- This happens if different version of the Defang CLI are used with the same AWS account. Each version one will try to update the CD stack to its version, back and forth. Make sure that all users have the same version of the CLI. Check the CLI version using `defang version`. + +### "invalid healthcheck: ingress ports require an HTTP healthcheck on `localhost`. + +- This message is displayed when `defang compose up` tries to deploy a service with an "ingress" port, if the service does not have a `healthcheck` which mentions `localhost`. Defang routes a load balancer to your service's ingress ports, and the loadbalancer needs to be able to check the health of the service. To solve this issue, ask yourself these two questions: + +1. Should my service be public? It's common to declare your container's ports using the Compose file "shorthand" syntax (`1234:1234`). This syntax can be understood as `[HOST:]CONTAINER`. If your service is not intended to be public, you do not need to declare a HOST port. For example: + + ```diff + services: + my-service: + image: my-image + ports: + - - "1234:1234" + + - "1234" + ``` +2. Does my healthcheck include the string `localhost`? It is very common to define a healthcheck by using `curl` or `wget` to make a request to `localhost`. So common, in fact, that defang will look for the string `localhost` in your healthcheck definition. For example, this healthcheck is valid: + + ```yaml + healthcheck: + test: ["CMD", "curl", "-f", "http://localhost:1234/health"] + ``` + + This healthcheck is not valid for `ingress` ports: + + ```yaml + healthcheck: + test: ["CMD", "./my-healthcheck"] + ``` + +### The build aborted with OutOfMemoryError: Container killed due to memory usage + +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 +``` From d7b4388bcbced623e9b1c8cbf442f130ab91849c Mon Sep 17 00:00:00 2001 From: commit111 Date: Mon, 2 Dec 2024 10:29:07 -0800 Subject: [PATCH 03/22] add correct hyperlinks --- blog/2024-02-12-announcing-defang-public-beta.md | 2 +- docs/faq/faq2.md | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/blog/2024-02-12-announcing-defang-public-beta.md b/blog/2024-02-12-announcing-defang-public-beta.md index 32487c918..e863dc62a 100644 --- a/blog/2024-02-12-announcing-defang-public-beta.md +++ b/blog/2024-02-12-announcing-defang-public-beta.md @@ -12,7 +12,7 @@ Ever since we shipped our Private Beta in the summer of 2023, we have been worki And so, today with our Public Beta, we are addressing this request. With today’s release of [Defang BYOC](https://docs.defang.io/docs/concepts/defang-byoc) (Bring-your-own-Cloud), you can now enjoy all the benefits of Defang **and** deploy applications to your own AWS account! Our Private Beta experience is still available as [Defang Playground](https://docs.defang.io/docs/concepts/defang-playground) for you to quickly and easily prototype applications and deploy them to our hosted environment. -You can learn more about Defang [here](https://docs.defang.io/docs/intro). Also check out our [tutorials](https://docs.defang.io/docs/category/tutorials), [samples](https://docs.defang.io/docs/samples), and [FAQ](https://docs.defang.io/docs/faq) to know more. +You can learn more about Defang [here](https://docs.defang.io/docs/intro). Also check out our [tutorials](https://docs.defang.io/docs/category/tutorials), [samples](https://docs.defang.io/docs/samples), and [FAQ](https://docs.defang.io/docs/category/faq) to know more. **Try the Public Beta!** diff --git a/docs/faq/faq2.md b/docs/faq/faq2.md index 1e37005ea..4e200f513 100644 --- a/docs/faq/faq2.md +++ b/docs/faq/faq2.md @@ -69,5 +69,5 @@ import {Button, ButtonGroup, FormGroup, FormLabel} from "@mui/material" 4. Alternatively, select the option "App Store and identified developers" to allow all applications from the App Store and identified developers to run. ### I'm getting a warning/error. What does it mean? -- See the Common Warnings and Errors page. +- See the [Common Error Messages](./warnings-errors.md) page. From bb3a6a52972a0e600051adba72fa045e8250c6b6 Mon Sep 17 00:00:00 2001 From: commit111 Date: Mon, 2 Dec 2024 10:34:43 -0800 Subject: [PATCH 04/22] delete old faq --- docs/faq.md | 190 ---------------------------------------------------- 1 file changed, 190 deletions(-) delete mode 100644 docs/faq.md diff --git a/docs/faq.md b/docs/faq.md deleted file mode 100644 index 149af90a0..000000000 --- a/docs/faq.md +++ /dev/null @@ -1,190 +0,0 @@ ---- -sidebar_position: 600 -title: FAQ -description: Frequently asked questions about Defang. ---- - - -# FAQ - -### Which cloud/region is the app being deployed to? - -- In the [Defang Playground](./concepts/defang-playground.md) the app is deployed to AWS `us-west-2`. In the [Defang BYOC](./concepts/defang-byoc.md) model, the region is determined by your [Defang BYOC Provider](/docs/category/providers) settings. - -### Can I bring my own AWS or other cloud account? - -- Yes! Defang makes it easy to deploy your application to your own cloud account. Please check out the [Defang BYOC](./concepts/defang-byoc.md) documentation for more information. - -### On AWS, can I deploy to services such as EC2, EKS, or Lambda? - -- The current release includes support for containers only, deployed to ECS. We are still exploring how to support additional execution models such as VMs and functions-as-a-service. However, using our Pulumi provider, it is possible to combine Defang services with other native AWS resources. - -### Can I access AWS storage services such as S3 or database services such as RDS? How? - -- Yes, you can access AWS services in the AWS Dashboard as you normally would when you are [deploying to your AWS account](./providers/aws) using Defang. In fact, you can access whatever other resources exist in the cloud account you are using for [Defang BYOC](./concepts/defang-byoc.md). - -### Can I run production apps with Defang? - -- Yes! Defang makes it easy to deploy your app on production-ready infrastructure in your own cloud account. For example, you can deploy your app to AWS with `defang up --provider=aws --mode=production`. Check out your preferred cloud provider on [Defang BYOC](./concepts/defang-byoc.md). - -### Does Defang support blue/green deployments? - -- Defang does not currently support Blue/Green deploys, but it does support rolling updates with the `production` deployment mode. `defang up --mode=production`. - -### Does Defang support rolling deployments? - -- Yes! Defang supports rolling updates with the `production` deployment mode. `defang up --mode=production`. - -### 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. - -### Can I deploy multiple services at once? - -- Yes! You can deploy multiple services at once by defining them in a single compose.yaml file. When you run `defang compose up`, Defang will deploy all the services defined in the file at once. - -### Can I deploy a service that depends on another service? - -- Defang does not currently support service dependencies. All services will be deployed simultaneously. Defang will however run multiple healthchecks before marking a service as healthy and spinning down any previously deployed services when using the `production` deployment mode. - -### Do you plan to support other clouds? - -- While we currently support [AWS](./concepts/defang-byoc#aws) for production and [DigitalOcean](./concepts/defang-byoc#digitalocean) in preview, we plan to support other clouds in future releases, such as [GCP](./providers/gcp.md) and [Azure](./providers/azure.md). - -### I'm having trouble running the binary on my Mac. What should I do? - -- MacOS users will need to allow the binary to run due to security settings: - 1. Attempt to run the binary. You'll see a security prompt preventing you from running it. - 2. Go to System Preferences > Privacy & Security > General. - 3. In the 'Allow applications downloaded from:' section, you should see a message about Defang being blocked. Click 'Open Anyway'. - 4. Alternatively, select the option "App Store and identified developers" to allow all applications from the App Store and identified developers to run. - -## Warnings - -### "The folder is not empty. Files may be overwritten." -- This message is displayed when you run `defang generate` and the target folder is not empty. If you proceed, Defang will overwrite any existing files with the same name. If you want to keep the existing files, you should move them to a different folder before running `defang generate` or pick a different target folder. - -### "environment variable not found" -- This message is displayed when you run `defang compose up` and the Compose file references an environment variable that is not set. If you proceed, the environment variable will be empty in the container. If you want to set the environment variable, you should set it in the environment where you run `defang compose up`. - -### "Unsupported platform" -- This message is displayed when you run `defang compose up` and the Compose file references a platform that is not supported by Defang. Defang Beta only supports Linux operating systems. - -### "not logged in" -- This message is displayed when you run `defang compose config` but you are not logged in. The displayed configuration will be incomplete. If you want to see the complete configuration, you should log in first using `defang login`. - -### "No port mode was specified; assuming 'host'" -- This message is displayed when you run `defang compose up` and the Compose file declares a `port` that does not specify a port `mode`. By default, Defang will keep the port private. If you want to expose the port to the public internet, you should specify the `mode` as `ingress`: -``` -services: - service1: - … - ports: - - target: 80 - mode: ingress -``` - -### "Published ports are not supported in ingress mode; assuming 'host'" -- This message is displayed when you run `defang compose up` and the Compose file declares a `port` with `mode` set to `ingress` and `published` set to a port number. Defang does not support published ports in ingress mode. If you want to expose the port to the public internet, you should specify the `mode` as `ingress` and remove the `published` setting. - -### "TCP ingress is not supported; assuming HTTP" -- This message is displayed when you run `defang compose up` and the Compose file declares a `port` with `mode` set to `ingress` and `protocol` set to `tcp`. Defang does not support arbitrary TCP ingress and will assume the port is used for HTTP traffic. To silence the warning, remove the `protocol` setting. - -### "unsupported compose directive" -- This message is displayed when you run `defang compose up` and the Compose file declares a directive that is not supported by Defang. The deployment will continue, but the unsupported directive will be ignored, which may cause unexpected behavior. - -### "no reservations specified; using limits as reservations" -- This message is displayed when you run `defang compose up` and the Compose file declares a `resource` with `limits` but no `reservations`. Defang will use the `limits` as `reservations` to ensure the container has enough resources. Specify `reservations` if you want to silence the warning or reserve a different amount of resources: -``` -services: - service1: - … - deploy: - resources: - reservations: - cpus: 0.5 - memory: 512MB -``` - -### "ingress port without healthcheck defaults to GET / HTTP/1.1" -- This message is displayed when you run `defang compose up` and the Compose file declares an `ingress` with a `port` but no `healthcheck`. Defang will assume the default healthcheck of `GET / HTTP/1.1` to ensure the port is healthy. Specify a `healthcheck` if you want to silence the warning or use a different healthcheck: -``` -services: - service1: - … - deploy: - healthcheck: - test: ["CMD", "curl", "-f", "http://localhost:80/health"] -``` - -### "missing memory reservation; specify deploy.resources.reservations.memory to avoid out-of-memory errors" -- This message is displayed when you run `defang compose up` and the Compose file doesn't specify a `memory` reservation. If available, Defang will use the `memory` limit as the `memory` reservation. Specify a `memory` reservation if you want to silence the warning or reserve a different amount of memory: -``` -services: - service1: - … - deploy: - resources: - reservations: - memory: 512MB -``` - -### "The build context contains more than 10 files" -- This message is displayed when you run `defang compose up` and the Compose file declares a `build` with a `context` that contains more than 10 files. Ensure the context refers to the correct folder. Defang will use the `context` as is, but you may experience slow build times. If you want to speed up the build, you should reduce the number of files in the `context`. - -### "AWS provider was selected, but AWS environment variables are not set" -- This message is displayed when you run `defang compose up` with the `--provider=aws` but none of the AWS environment variables were set. If you proceed, the deployment might fail, unless you have defined defined `default` credentials in the AWS configuration files or are running on an AWS instance. - -### "Using Defang provider, but AWS environment variables were detected" -- This message is displayed when you run `defang compose up` with the `--provider=defang` but AWS environment variables were detected. The AWS environment variables will be ignored. - -## Errors - -### "Stack:… is in UPDATE_COMPLETE_CLEANUP_IN_PROGRESS state and cannot be updated" -- This happens if different version of the Defang CLI are used with the same AWS account. Each version one will try to update the CD stack to its version, back and forth. Make sure that all users have the same version of the CLI. Check the CLI version using `defang version`. - -### "invalid healthcheck: ingress ports require an HTTP healthcheck on `localhost`. - -- This message is displayed when `defang compose up` tries to deploy a service with an "ingress" port, if the service does not have a `healthcheck` which mentions `localhost`. Defang routes a load balancer to your service's ingress ports, and the loadbalancer needs to be able to check the health of the service. To solve this issue, ask yourself these two questions: - -1. Should my service be public? It's common to declare your container's ports using the Compose file "shorthand" syntax (`1234:1234`). This syntax can be understood as `[HOST:]CONTAINER`. If your service is not intended to be public, you do not need to declare a HOST port. For example: - - ```diff - services: - my-service: - image: my-image - ports: - - - "1234:1234" - + - "1234" - ``` -2. Does my healthcheck include the string `localhost`? It is very common to define a healthcheck by using `curl` or `wget` to make a request to `localhost`. So common, in fact, that defang will look for the string `localhost` in your healthcheck definition. For example, this healthcheck is valid: - - ```yaml - healthcheck: - test: ["CMD", "curl", "-f", "http://localhost:1234/health"] - ``` - - This healthcheck is not valid for `ingress` ports: - - ```yaml - healthcheck: - test: ["CMD", "./my-healthcheck"] - ``` - -### The build aborted with OutOfMemoryError: Container killed due to memory usage - -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 -``` From d6f5e3ffad1920e223df1e2fe789de7d73619e24 Mon Sep 17 00:00:00 2001 From: commit111 Date: Mon, 2 Dec 2024 10:36:28 -0800 Subject: [PATCH 05/22] rename faq2 to questions --- docs/faq/{faq2.md => questions.md} | 0 1 file changed, 0 insertions(+), 0 deletions(-) rename docs/faq/{faq2.md => questions.md} (100%) diff --git a/docs/faq/faq2.md b/docs/faq/questions.md similarity index 100% rename from docs/faq/faq2.md rename to docs/faq/questions.md From cc1e73c028c34e1825cb2df0e9d0775d7c50f607 Mon Sep 17 00:00:00 2001 From: commit111 Date: Mon, 2 Dec 2024 12:21:03 -0800 Subject: [PATCH 06/22] minor wording fix --- docs/faq/questions.md | 2 +- docs/faq/warnings-errors.md | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/faq/questions.md b/docs/faq/questions.md index 4e200f513..2c20a4c9b 100644 --- a/docs/faq/questions.md +++ b/docs/faq/questions.md @@ -69,5 +69,5 @@ import {Button, ButtonGroup, FormGroup, FormLabel} from "@mui/material" 4. Alternatively, select the option "App Store and identified developers" to allow all applications from the App Store and identified developers to run. ### I'm getting a warning/error. What does it mean? -- See the [Common Error Messages](./warnings-errors.md) page. +- Please see the [Common Error Messages](./warnings-errors.md) page. diff --git a/docs/faq/warnings-errors.md b/docs/faq/warnings-errors.md index d99cc5eb9..db05a633a 100644 --- 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 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 From 26767d7a76c5534e790ae008e4690785b1909a64 Mon Sep 17 00:00:00 2001 From: commit111 Date: Mon, 2 Dec 2024 14:01:32 -0800 Subject: [PATCH 07/22] add comparison faq --- docs/faq/questions.md | 11 +++++++++++ 1 file changed, 11 insertions(+) diff --git a/docs/faq/questions.md b/docs/faq/questions.md index 2c20a4c9b..e5db4143a 100644 --- a/docs/faq/questions.md +++ b/docs/faq/questions.md @@ -58,6 +58,17 @@ import {Button, ButtonGroup, FormGroup, FormLabel} from "@mui/material" - Defang does not currently support service dependencies. All services will be deployed simultaneously. Defang will however run multiple healthchecks before marking a service as healthy and spinning down any previously deployed services when using the `production` deployment mode. +## Feature Comparisons + +### Is Defang a run-time platform? +- No. Defang is not a run-time platform. Instead, it lets you host and run your application on a [cloud provider](../category/providers) of your choice. You can think of it as a tool that makes it way easier to deploy to that cloud provider. + +### What is the difference between Defang and platforms such as Vercel, fly.io, and Railway? +- Defang is a tool that helps you get your application deployed to a [cloud provider](../category/providers) of your choice, and it is not a platform. Unlike platforms, Defang does not host your application. We do provide [Defang Playground](../concepts/defang-playground), but it is meant to be used as a testing environment only. + +### What is the difference between Defang and tools such as SST? +- Defang is cloud-agnostic and language-agnostic, meaning that it is designed to work with different [cloud providers](../category/providers), and programming languages. Since Defang is not tied to just one cloud or language, this allows for greater flexibility in a wide range of cases. Another difference is that Defang follows the [Compose specification](https://docs.docker.com/compose/compose-file/), allowing it to work smoothly with various container platforms such as Docker. + ## Troubleshooting ### I'm having trouble running the binary on my Mac. What should I do? From 66a6e804b878f1c077fe03b155af517b7bc51d7c Mon Sep 17 00:00:00 2001 From: commit111 Date: Mon, 2 Dec 2024 14:15:16 -0800 Subject: [PATCH 08/22] fix merge conflict --- docs/concepts/defang-byoc.md | 4 ---- docs/faq/warnings-errors.md | 2 +- docs/providers/aws/aws.md | 4 ---- 3 files changed, 1 insertion(+), 9 deletions(-) diff --git a/docs/concepts/defang-byoc.md b/docs/concepts/defang-byoc.md index d309d52d7..aff4c7d5b 100644 --- a/docs/concepts/defang-byoc.md +++ b/docs/concepts/defang-byoc.md @@ -29,10 +29,6 @@ $ export DEFANG_PROVIDER=digitalocean ## AWS -:::info -The Public Beta of the v1 Defang BYOC AWS Provider is released as of Feb 1 2024. -::: - Please read the [AWS Provider](../providers/aws/aws.md) documentation for more details about how the AWS provider works and how to get started. ## DigitalOcean diff --git a/docs/faq/warnings-errors.md b/docs/faq/warnings-errors.md index db05a633a..caabd0d8e 100644 --- a/docs/faq/warnings-errors.md +++ b/docs/faq/warnings-errors.md @@ -15,7 +15,7 @@ Here are the meanings of common [warning](#warnings) and [error](#errors) messag - This message is displayed when you run `defang compose up` and the Compose file references an environment variable that is not set. If you proceed, the environment variable will be empty in the container. If you want to set the environment variable, you should set it in the environment where you run `defang compose up`. ### "Unsupported platform" -- This message is displayed when you run `defang compose up` and the Compose file references a platform that is not supported by Defang. Defang Beta only supports Linux operating systems. +- This message is displayed when you run `defang compose up` and the Compose file references a platform that is not supported by Defang. ### "not logged in" - This message is displayed when you run `defang compose config` but you are not logged in. The displayed configuration will be incomplete. If you want to see the complete configuration, you should log in first using `defang login`. diff --git a/docs/providers/aws/aws.md b/docs/providers/aws/aws.md index 88b77e9b7..cf6cfcf98 100644 --- a/docs/providers/aws/aws.md +++ b/docs/providers/aws/aws.md @@ -6,10 +6,6 @@ sidebar_position: 000 # AWS -:::info -Public Beta of the v1 Defang BYOC AWS Provider is released as of Feb 1 2024. -::: - Why should you use Defang with AWS? Defang allows you to easily create and manage full, scalable applications with AWS. Defang aims to make it easier to deploy your services to the cloud. Don't waste your time learning the ins and outs of AWS, deciding which of the 200+ services to use, and then writing the infrastructure code to deploy your services, and making sure they are properly secured. Defang does all of that for you. ## Getting Started From 2d65fb74ad8505ed8a0ed95473155b4b95612704 Mon Sep 17 00:00:00 2001 From: commit111 Date: Mon, 2 Dec 2024 10:24:53 -0800 Subject: [PATCH 09/22] categorize faq with headings --- docs/faq/faq2.md | 73 ++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 73 insertions(+) create mode 100644 docs/faq/faq2.md diff --git a/docs/faq/faq2.md b/docs/faq/faq2.md new file mode 100644 index 000000000..1e37005ea --- /dev/null +++ b/docs/faq/faq2.md @@ -0,0 +1,73 @@ +--- +sidebar_position: 600 +title: Frequently Asked Questions +description: Frequently asked questions about Defang. +--- +import {Button, ButtonGroup, FormGroup, FormLabel} from "@mui/material" + +# Frequently Asked Questions (FAQ) + +## Deployment and Infrastructure +### Which cloud/region is the app being deployed to? + +- In the [Defang Playground](../concepts/defang-playground.md), the app is deployed to AWS `us-west-2`. In the [Defang BYOC](../concepts/defang-byoc.md) model, the region is determined by your [Defang BYOC Provider](/docs/category/providers) settings. + +### Can I bring my own AWS or other cloud account? + +- Yes! Defang makes it easy to deploy your application to your own cloud account. Please check out the [Defang BYOC](../concepts/defang-byoc.md) documentation for more information. + +### On AWS, can I deploy to services such as EC2, EKS, or Lambda? + +- The current release includes support for containers only, deployed to ECS. We are still exploring how to support additional execution models such as VMs and functions-as-a-service. However, using our Pulumi provider, it is possible to combine Defang services with other native AWS resources. + +### Can I access AWS storage services such as S3 or database services such as RDS? How? + +- Yes! You can access AWS services in the AWS Dashboard as you normally would when you are [deploying to your AWS account](../providers/aws) using Defang. In fact, you can access whatever other resources exist in the cloud account you are using for [Defang BYOC](../concepts/defang-byoc.md). + +### Do you plan to support other clouds? + +- While we currently support [AWS](../concepts/defang-byoc#aws) for production and [DigitalOcean](../concepts/defang-byoc#digitalocean) in preview, we plan to support other clouds in future releases, such as [GCP](../providers/gcp.md) and [Azure](../providers/azure.md). + +## Deployment Process + +### Can I run production apps with Defang? + +- Yes! Defang makes it easy to deploy your app on production-ready infrastructure in your own cloud account. For example, you can deploy your app to AWS with `defang up --provider=aws --mode=production`. Check out your preferred cloud provider on [Defang BYOC](../concepts/defang-byoc.md). + +### Does Defang support blue/green deployments? + +- Defang does not currently support Blue/Green deploys, but it does support rolling updates with the `production` deployment mode. `defang up --mode=production`. + +### Does Defang support rolling deployments? + +- Yes! Defang supports rolling updates with the `production` deployment mode. `defang up --mode=production`. + +### 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. + +### Can I deploy multiple services at once? + +- Yes! You can deploy multiple services at once by defining them in a single compose.yaml file. When you run `defang compose up`, Defang will deploy all the services defined in the file at once. + +### Can I deploy a service that depends on another service? + +- Defang does not currently support service dependencies. All services will be deployed simultaneously. Defang will however run multiple healthchecks before marking a service as healthy and spinning down any previously deployed services when using the `production` deployment mode. + +## Troubleshooting + +### I'm having trouble running the binary on my Mac. What should I do? + +- MacOS users will need to allow the binary to run due to security settings: + 1. Attempt to run the binary. You'll see a security prompt preventing you from running it. + 2. Go to System Preferences > Privacy & Security > General. + 3. In the 'Allow applications downloaded from:' section, you should see a message about Defang being blocked. Click 'Open Anyway'. + 4. Alternatively, select the option "App Store and identified developers" to allow all applications from the App Store and identified developers to run. + +### I'm getting a warning/error. What does it mean? +- See the Common Warnings and Errors page. + From de8c1418841c3c22799db1d78b0b7c74ef408e6c Mon Sep 17 00:00:00 2001 From: commit111 Date: Mon, 2 Dec 2024 10:25:23 -0800 Subject: [PATCH 10/22] add new warning/error messages section --- docs/faq/_category_.json | 9 +++ docs/faq/warnings-errors.md | 133 ++++++++++++++++++++++++++++++++++++ 2 files changed, 142 insertions(+) create mode 100644 docs/faq/_category_.json create mode 100644 docs/faq/warnings-errors.md diff --git a/docs/faq/_category_.json b/docs/faq/_category_.json new file mode 100644 index 000000000..dd0a2f94d --- /dev/null +++ b/docs/faq/_category_.json @@ -0,0 +1,9 @@ +{ + "label": "FAQ", + "position": 600, + "link": { + "type": "generated-index", + "description": "Wondering about something? Check out one of the guides below for additional support." + } + } + \ No newline at end of file diff --git a/docs/faq/warnings-errors.md b/docs/faq/warnings-errors.md new file mode 100644 index 000000000..d99cc5eb9 --- /dev/null +++ b/docs/faq/warnings-errors.md @@ -0,0 +1,133 @@ +--- +sidebar_position: 700 +title: Common Error Messages +description: Common warnings and error messages, and their meanings. +--- + +Here are meanings of common [warning](#warnings) and [error](#errors) messages you may encounter in the Defang CLI. + +## Warnings + +### "The folder is not empty. Files may be overwritten." +- This message is displayed when you run `defang generate` and the target folder is not empty. If you proceed, Defang will overwrite any existing files with the same name. If you want to keep the existing files, you should move them to a different folder before running `defang generate` or pick a different target folder. + +### "environment variable not found" +- This message is displayed when you run `defang compose up` and the Compose file references an environment variable that is not set. If you proceed, the environment variable will be empty in the container. If you want to set the environment variable, you should set it in the environment where you run `defang compose up`. + +### "Unsupported platform" +- This message is displayed when you run `defang compose up` and the Compose file references a platform that is not supported by Defang. Defang Beta only supports Linux operating systems. + +### "not logged in" +- This message is displayed when you run `defang compose config` but you are not logged in. The displayed configuration will be incomplete. If you want to see the complete configuration, you should log in first using `defang login`. + +### "No port mode was specified; assuming 'host'" +- This message is displayed when you run `defang compose up` and the Compose file declares a `port` that does not specify a port `mode`. By default, Defang will keep the port private. If you want to expose the port to the public internet, you should specify the `mode` as `ingress`: +``` +services: + service1: + … + ports: + - target: 80 + mode: ingress +``` + +### "Published ports are not supported in ingress mode; assuming 'host'" +- This message is displayed when you run `defang compose up` and the Compose file declares a `port` with `mode` set to `ingress` and `published` set to a port number. Defang does not support published ports in ingress mode. If you want to expose the port to the public internet, you should specify the `mode` as `ingress` and remove the `published` setting. + +### "TCP ingress is not supported; assuming HTTP" +- This message is displayed when you run `defang compose up` and the Compose file declares a `port` with `mode` set to `ingress` and `protocol` set to `tcp`. Defang does not support arbitrary TCP ingress and will assume the port is used for HTTP traffic. To silence the warning, remove the `protocol` setting. + +### "unsupported compose directive" +- This message is displayed when you run `defang compose up` and the Compose file declares a directive that is not supported by Defang. The deployment will continue, but the unsupported directive will be ignored, which may cause unexpected behavior. + +### "no reservations specified; using limits as reservations" +- This message is displayed when you run `defang compose up` and the Compose file declares a `resource` with `limits` but no `reservations`. Defang will use the `limits` as `reservations` to ensure the container has enough resources. Specify `reservations` if you want to silence the warning or reserve a different amount of resources: +``` +services: + service1: + … + deploy: + resources: + reservations: + cpus: 0.5 + memory: 512MB +``` + +### "ingress port without healthcheck defaults to GET / HTTP/1.1" +- This message is displayed when you run `defang compose up` and the Compose file declares an `ingress` with a `port` but no `healthcheck`. Defang will assume the default healthcheck of `GET / HTTP/1.1` to ensure the port is healthy. Specify a `healthcheck` if you want to silence the warning or use a different healthcheck: +``` +services: + service1: + … + deploy: + healthcheck: + test: ["CMD", "curl", "-f", "http://localhost:80/health"] +``` + +### "missing memory reservation; specify deploy.resources.reservations.memory to avoid out-of-memory errors" +- This message is displayed when you run `defang compose up` and the Compose file doesn't specify a `memory` reservation. If available, Defang will use the `memory` limit as the `memory` reservation. Specify a `memory` reservation if you want to silence the warning or reserve a different amount of memory: +``` +services: + service1: + … + deploy: + resources: + reservations: + memory: 512MB +``` + +### "The build context contains more than 10 files" +- This message is displayed when you run `defang compose up` and the Compose file declares a `build` with a `context` that contains more than 10 files. Ensure the context refers to the correct folder. Defang will use the `context` as is, but you may experience slow build times. If you want to speed up the build, you should reduce the number of files in the `context`. + +### "AWS provider was selected, but AWS environment variables are not set" +- This message is displayed when you run `defang compose up` with the `--provider=aws` but none of the AWS environment variables were set. If you proceed, the deployment might fail, unless you have defined defined `default` credentials in the AWS configuration files or are running on an AWS instance. + +### "Using Defang provider, but AWS environment variables were detected" +- This message is displayed when you run `defang compose up` with the `--provider=defang` but AWS environment variables were detected. The AWS environment variables will be ignored. + +## Errors + +### "Stack:… is in UPDATE_COMPLETE_CLEANUP_IN_PROGRESS state and cannot be updated" +- This happens if different version of the Defang CLI are used with the same AWS account. Each version one will try to update the CD stack to its version, back and forth. Make sure that all users have the same version of the CLI. Check the CLI version using `defang version`. + +### "invalid healthcheck: ingress ports require an HTTP healthcheck on `localhost`. + +- This message is displayed when `defang compose up` tries to deploy a service with an "ingress" port, if the service does not have a `healthcheck` which mentions `localhost`. Defang routes a load balancer to your service's ingress ports, and the loadbalancer needs to be able to check the health of the service. To solve this issue, ask yourself these two questions: + +1. Should my service be public? It's common to declare your container's ports using the Compose file "shorthand" syntax (`1234:1234`). This syntax can be understood as `[HOST:]CONTAINER`. If your service is not intended to be public, you do not need to declare a HOST port. For example: + + ```diff + services: + my-service: + image: my-image + ports: + - - "1234:1234" + + - "1234" + ``` +2. Does my healthcheck include the string `localhost`? It is very common to define a healthcheck by using `curl` or `wget` to make a request to `localhost`. So common, in fact, that defang will look for the string `localhost` in your healthcheck definition. For example, this healthcheck is valid: + + ```yaml + healthcheck: + test: ["CMD", "curl", "-f", "http://localhost:1234/health"] + ``` + + This healthcheck is not valid for `ingress` ports: + + ```yaml + healthcheck: + test: ["CMD", "./my-healthcheck"] + ``` + +### The build aborted with OutOfMemoryError: Container killed due to memory usage + +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 +``` From 64857a3aa20da58e98435d3f31fb98cea1758416 Mon Sep 17 00:00:00 2001 From: commit111 Date: Mon, 2 Dec 2024 10:29:07 -0800 Subject: [PATCH 11/22] add correct hyperlinks --- blog/2024-02-12-announcing-defang-public-beta.md | 2 +- docs/faq/faq2.md | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/blog/2024-02-12-announcing-defang-public-beta.md b/blog/2024-02-12-announcing-defang-public-beta.md index 32487c918..e863dc62a 100644 --- a/blog/2024-02-12-announcing-defang-public-beta.md +++ b/blog/2024-02-12-announcing-defang-public-beta.md @@ -12,7 +12,7 @@ Ever since we shipped our Private Beta in the summer of 2023, we have been worki And so, today with our Public Beta, we are addressing this request. With today’s release of [Defang BYOC](https://docs.defang.io/docs/concepts/defang-byoc) (Bring-your-own-Cloud), you can now enjoy all the benefits of Defang **and** deploy applications to your own AWS account! Our Private Beta experience is still available as [Defang Playground](https://docs.defang.io/docs/concepts/defang-playground) for you to quickly and easily prototype applications and deploy them to our hosted environment. -You can learn more about Defang [here](https://docs.defang.io/docs/intro). Also check out our [tutorials](https://docs.defang.io/docs/category/tutorials), [samples](https://docs.defang.io/docs/samples), and [FAQ](https://docs.defang.io/docs/faq) to know more. +You can learn more about Defang [here](https://docs.defang.io/docs/intro). Also check out our [tutorials](https://docs.defang.io/docs/category/tutorials), [samples](https://docs.defang.io/docs/samples), and [FAQ](https://docs.defang.io/docs/category/faq) to know more. **Try the Public Beta!** diff --git a/docs/faq/faq2.md b/docs/faq/faq2.md index 1e37005ea..4e200f513 100644 --- a/docs/faq/faq2.md +++ b/docs/faq/faq2.md @@ -69,5 +69,5 @@ import {Button, ButtonGroup, FormGroup, FormLabel} from "@mui/material" 4. Alternatively, select the option "App Store and identified developers" to allow all applications from the App Store and identified developers to run. ### I'm getting a warning/error. What does it mean? -- See the Common Warnings and Errors page. +- See the [Common Error Messages](./warnings-errors.md) page. From 43fdef3b0286298b7c3fc2586293fe8fc516a4dc Mon Sep 17 00:00:00 2001 From: commit111 Date: Mon, 2 Dec 2024 10:34:43 -0800 Subject: [PATCH 12/22] delete old faq --- docs/faq.md | 190 ---------------------------------------------------- 1 file changed, 190 deletions(-) delete mode 100644 docs/faq.md diff --git a/docs/faq.md b/docs/faq.md deleted file mode 100644 index ed2fa9cd4..000000000 --- a/docs/faq.md +++ /dev/null @@ -1,190 +0,0 @@ ---- -sidebar_position: 600 -title: FAQ -description: Frequently asked questions about Defang. ---- - - -# FAQ - -### Which cloud/region is the app being deployed to? - -- In the [Defang Playground](./concepts/defang-playground.md) the app is deployed to AWS `us-west-2`. In the [Defang BYOC](./concepts/defang-byoc.md) model, the region is determined by your [Defang BYOC Provider](/docs/category/providers) settings. - -### Can I bring my own AWS or other cloud account? - -- Yes! Defang makes it easy to deploy your application to your own cloud account. Please check out the [Defang BYOC](./concepts/defang-byoc.md) documentation for more information. - -### On AWS, can I deploy to services such as EC2, EKS, or Lambda? - -- The current release includes support for containers only, deployed to ECS. We are still exploring how to support additional execution models such as VMs and functions-as-a-service. However, using our Pulumi provider, it is possible to combine Defang services with other native AWS resources. - -### Can I access AWS storage services such as S3 or database services such as RDS? How? - -- Yes, you can access AWS services in the AWS Dashboard as you normally would when you are [deploying to your AWS account](./providers/aws) using Defang. In fact, you can access whatever other resources exist in the cloud account you are using for [Defang BYOC](./concepts/defang-byoc.md). - -### Can I run production apps with Defang? - -- Yes! Defang makes it easy to deploy your app on production-ready infrastructure in your own cloud account. For example, you can deploy your app to AWS with `defang up --provider=aws --mode=production`. Check out your preferred cloud provider on [Defang BYOC](./concepts/defang-byoc.md). - -### Does Defang support blue/green deployments? - -- Defang does not currently support Blue/Green deploys, but it does support rolling updates with the `production` deployment mode. `defang up --mode=production`. - -### Does Defang support rolling deployments? - -- Yes! Defang supports rolling updates with the `production` deployment mode. `defang up --mode=production`. - -### 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. - -### Can I deploy multiple services at once? - -- Yes! You can deploy multiple services at once by defining them in a single compose.yaml file. When you run `defang compose up`, Defang will deploy all the services defined in the file at once. - -### Can I deploy a service that depends on another service? - -- Defang does not currently support service dependencies. All services will be deployed simultaneously. Defang will however run multiple healthchecks before marking a service as healthy and spinning down any previously deployed services when using the `production` deployment mode. - -### Do you plan to support other clouds? - -- While we currently support [AWS](./concepts/defang-byoc#aws) for production and [DigitalOcean](./concepts/defang-byoc#digitalocean) in preview, we plan to support other clouds in future releases, such as [GCP](./providers/gcp.md) and [Azure](./providers/azure.md). - -### I'm having trouble running the binary on my Mac. What should I do? - -- MacOS users will need to allow the binary to run due to security settings: - 1. Attempt to run the binary. You'll see a security prompt preventing you from running it. - 2. Go to System Preferences > Privacy & Security > General. - 3. In the 'Allow applications downloaded from:' section, you should see a message about Defang being blocked. Click 'Open Anyway'. - 4. Alternatively, select the option "App Store and identified developers" to allow all applications from the App Store and identified developers to run. - -## Warnings - -### "The folder is not empty. Files may be overwritten." -- This message is displayed when you run `defang generate` and the target folder is not empty. If you proceed, Defang will overwrite any existing files with the same name. If you want to keep the existing files, you should move them to a different folder before running `defang generate` or pick a different target folder. - -### "environment variable not found" -- This message is displayed when you run `defang compose up` and the Compose file references an environment variable that is not set. If you proceed, the environment variable will be empty in the container. If you want to set the environment variable, you should set it in the environment where you run `defang compose up`. - -### "Unsupported platform" -- This message is displayed when you run `defang compose up` and the Compose file references a platform that is not supported by Defang. - -### "not logged in" -- This message is displayed when you run `defang compose config` but you are not logged in. The displayed configuration will be incomplete. If you want to see the complete configuration, you should log in first using `defang login`. - -### "No port mode was specified; assuming 'host'" -- This message is displayed when you run `defang compose up` and the Compose file declares a `port` that does not specify a port `mode`. By default, Defang will keep the port private. If you want to expose the port to the public internet, you should specify the `mode` as `ingress`: -``` -services: - service1: - … - ports: - - target: 80 - mode: ingress -``` - -### "Published ports are not supported in ingress mode; assuming 'host'" -- This message is displayed when you run `defang compose up` and the Compose file declares a `port` with `mode` set to `ingress` and `published` set to a port number. Defang does not support published ports in ingress mode. If you want to expose the port to the public internet, you should specify the `mode` as `ingress` and remove the `published` setting. - -### "TCP ingress is not supported; assuming HTTP" -- This message is displayed when you run `defang compose up` and the Compose file declares a `port` with `mode` set to `ingress` and `protocol` set to `tcp`. Defang does not support arbitrary TCP ingress and will assume the port is used for HTTP traffic. To silence the warning, remove the `protocol` setting. - -### "unsupported compose directive" -- This message is displayed when you run `defang compose up` and the Compose file declares a directive that is not supported by Defang. The deployment will continue, but the unsupported directive will be ignored, which may cause unexpected behavior. - -### "no reservations specified; using limits as reservations" -- This message is displayed when you run `defang compose up` and the Compose file declares a `resource` with `limits` but no `reservations`. Defang will use the `limits` as `reservations` to ensure the container has enough resources. Specify `reservations` if you want to silence the warning or reserve a different amount of resources: -``` -services: - service1: - … - deploy: - resources: - reservations: - cpus: 0.5 - memory: 512MB -``` - -### "ingress port without healthcheck defaults to GET / HTTP/1.1" -- This message is displayed when you run `defang compose up` and the Compose file declares an `ingress` with a `port` but no `healthcheck`. Defang will assume the default healthcheck of `GET / HTTP/1.1` to ensure the port is healthy. Specify a `healthcheck` if you want to silence the warning or use a different healthcheck: -``` -services: - service1: - … - deploy: - healthcheck: - test: ["CMD", "curl", "-f", "http://localhost:80/health"] -``` - -### "missing memory reservation; specify deploy.resources.reservations.memory to avoid out-of-memory errors" -- This message is displayed when you run `defang compose up` and the Compose file doesn't specify a `memory` reservation. If available, Defang will use the `memory` limit as the `memory` reservation. Specify a `memory` reservation if you want to silence the warning or reserve a different amount of memory: -``` -services: - service1: - … - deploy: - resources: - reservations: - memory: 512MB -``` - -### "The build context contains more than 10 files" -- This message is displayed when you run `defang compose up` and the Compose file declares a `build` with a `context` that contains more than 10 files. Ensure the context refers to the correct folder. Defang will use the `context` as is, but you may experience slow build times. If you want to speed up the build, you should reduce the number of files in the `context`. - -### "AWS provider was selected, but AWS environment variables are not set" -- This message is displayed when you run `defang compose up` with the `--provider=aws` but none of the AWS environment variables were set. If you proceed, the deployment might fail, unless you have defined defined `default` credentials in the AWS configuration files or are running on an AWS instance. - -### "Using Defang provider, but AWS environment variables were detected" -- This message is displayed when you run `defang compose up` with the `--provider=defang` but AWS environment variables were detected. The AWS environment variables will be ignored. - -## Errors - -### "Stack:… is in UPDATE_COMPLETE_CLEANUP_IN_PROGRESS state and cannot be updated" -- This happens if different version of the Defang CLI are used with the same AWS account. Each version one will try to update the CD stack to its version, back and forth. Make sure that all users have the same version of the CLI. Check the CLI version using `defang version`. - -### "invalid healthcheck: ingress ports require an HTTP healthcheck on `localhost`. - -- This message is displayed when `defang compose up` tries to deploy a service with an "ingress" port, if the service does not have a `healthcheck` which mentions `localhost`. Defang routes a load balancer to your service's ingress ports, and the loadbalancer needs to be able to check the health of the service. To solve this issue, ask yourself these two questions: - -1. Should my service be public? It's common to declare your container's ports using the Compose file "shorthand" syntax (`1234:1234`). This syntax can be understood as `[HOST:]CONTAINER`. If your service is not intended to be public, you do not need to declare a HOST port. For example: - - ```diff - services: - my-service: - image: my-image - ports: - - - "1234:1234" - + - "1234" - ``` -2. Does my healthcheck include the string `localhost`? It is very common to define a healthcheck by using `curl` or `wget` to make a request to `localhost`. So common, in fact, that defang will look for the string `localhost` in your healthcheck definition. For example, this healthcheck is valid: - - ```yaml - healthcheck: - test: ["CMD", "curl", "-f", "http://localhost:1234/health"] - ``` - - This healthcheck is not valid for `ingress` ports: - - ```yaml - healthcheck: - test: ["CMD", "./my-healthcheck"] - ``` - -### The build aborted with OutOfMemoryError: Container killed due to memory usage - -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 -``` From 3402f6e73ba263d771a27be9afc544ceeb87b0a4 Mon Sep 17 00:00:00 2001 From: commit111 Date: Mon, 2 Dec 2024 10:36:28 -0800 Subject: [PATCH 13/22] rename faq2 to questions --- docs/faq/{faq2.md => questions.md} | 0 1 file changed, 0 insertions(+), 0 deletions(-) rename docs/faq/{faq2.md => questions.md} (100%) diff --git a/docs/faq/faq2.md b/docs/faq/questions.md similarity index 100% rename from docs/faq/faq2.md rename to docs/faq/questions.md From 9ce65f289fc1ed15fd0ed8de8991a620f07698ce Mon Sep 17 00:00:00 2001 From: commit111 Date: Mon, 2 Dec 2024 12:21:03 -0800 Subject: [PATCH 14/22] minor wording fix --- docs/faq/questions.md | 2 +- docs/faq/warnings-errors.md | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/faq/questions.md b/docs/faq/questions.md index 4e200f513..2c20a4c9b 100644 --- a/docs/faq/questions.md +++ b/docs/faq/questions.md @@ -69,5 +69,5 @@ import {Button, ButtonGroup, FormGroup, FormLabel} from "@mui/material" 4. Alternatively, select the option "App Store and identified developers" to allow all applications from the App Store and identified developers to run. ### I'm getting a warning/error. What does it mean? -- See the [Common Error Messages](./warnings-errors.md) page. +- Please see the [Common Error Messages](./warnings-errors.md) page. diff --git a/docs/faq/warnings-errors.md b/docs/faq/warnings-errors.md index d99cc5eb9..db05a633a 100644 --- 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 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 From 90414b02105bade5c2eaaf8f0a1a8def4de55717 Mon Sep 17 00:00:00 2001 From: commit111 Date: Mon, 2 Dec 2024 14:01:32 -0800 Subject: [PATCH 15/22] add comparison faq --- docs/faq/questions.md | 11 +++++++++++ 1 file changed, 11 insertions(+) diff --git a/docs/faq/questions.md b/docs/faq/questions.md index 2c20a4c9b..e5db4143a 100644 --- a/docs/faq/questions.md +++ b/docs/faq/questions.md @@ -58,6 +58,17 @@ import {Button, ButtonGroup, FormGroup, FormLabel} from "@mui/material" - Defang does not currently support service dependencies. All services will be deployed simultaneously. Defang will however run multiple healthchecks before marking a service as healthy and spinning down any previously deployed services when using the `production` deployment mode. +## Feature Comparisons + +### Is Defang a run-time platform? +- No. Defang is not a run-time platform. Instead, it lets you host and run your application on a [cloud provider](../category/providers) of your choice. You can think of it as a tool that makes it way easier to deploy to that cloud provider. + +### What is the difference between Defang and platforms such as Vercel, fly.io, and Railway? +- Defang is a tool that helps you get your application deployed to a [cloud provider](../category/providers) of your choice, and it is not a platform. Unlike platforms, Defang does not host your application. We do provide [Defang Playground](../concepts/defang-playground), but it is meant to be used as a testing environment only. + +### What is the difference between Defang and tools such as SST? +- Defang is cloud-agnostic and language-agnostic, meaning that it is designed to work with different [cloud providers](../category/providers), and programming languages. Since Defang is not tied to just one cloud or language, this allows for greater flexibility in a wide range of cases. Another difference is that Defang follows the [Compose specification](https://docs.docker.com/compose/compose-file/), allowing it to work smoothly with various container platforms such as Docker. + ## Troubleshooting ### I'm having trouble running the binary on my Mac. What should I do? From 43f1e33d731cba6b4b6fefc606103358b4809b0f Mon Sep 17 00:00:00 2001 From: commit111 Date: Mon, 2 Dec 2024 14:15:16 -0800 Subject: [PATCH 16/22] fix merge conflict --- docs/faq/warnings-errors.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/faq/warnings-errors.md b/docs/faq/warnings-errors.md index db05a633a..caabd0d8e 100644 --- a/docs/faq/warnings-errors.md +++ b/docs/faq/warnings-errors.md @@ -15,7 +15,7 @@ Here are the meanings of common [warning](#warnings) and [error](#errors) messag - This message is displayed when you run `defang compose up` and the Compose file references an environment variable that is not set. If you proceed, the environment variable will be empty in the container. If you want to set the environment variable, you should set it in the environment where you run `defang compose up`. ### "Unsupported platform" -- This message is displayed when you run `defang compose up` and the Compose file references a platform that is not supported by Defang. Defang Beta only supports Linux operating systems. +- This message is displayed when you run `defang compose up` and the Compose file references a platform that is not supported by Defang. ### "not logged in" - This message is displayed when you run `defang compose config` but you are not logged in. The displayed configuration will be incomplete. If you want to see the complete configuration, you should log in first using `defang login`. From e0cadcc17ca37344d9a9d7e88c00e0a0ee76c9dd Mon Sep 17 00:00:00 2001 From: commit111 Date: Mon, 2 Dec 2024 10:24:53 -0800 Subject: [PATCH 17/22] categorize faq with headings --- docs/faq/faq2.md | 73 ++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 73 insertions(+) create mode 100644 docs/faq/faq2.md diff --git a/docs/faq/faq2.md b/docs/faq/faq2.md new file mode 100644 index 000000000..1e37005ea --- /dev/null +++ b/docs/faq/faq2.md @@ -0,0 +1,73 @@ +--- +sidebar_position: 600 +title: Frequently Asked Questions +description: Frequently asked questions about Defang. +--- +import {Button, ButtonGroup, FormGroup, FormLabel} from "@mui/material" + +# Frequently Asked Questions (FAQ) + +## Deployment and Infrastructure +### Which cloud/region is the app being deployed to? + +- In the [Defang Playground](../concepts/defang-playground.md), the app is deployed to AWS `us-west-2`. In the [Defang BYOC](../concepts/defang-byoc.md) model, the region is determined by your [Defang BYOC Provider](/docs/category/providers) settings. + +### Can I bring my own AWS or other cloud account? + +- Yes! Defang makes it easy to deploy your application to your own cloud account. Please check out the [Defang BYOC](../concepts/defang-byoc.md) documentation for more information. + +### On AWS, can I deploy to services such as EC2, EKS, or Lambda? + +- The current release includes support for containers only, deployed to ECS. We are still exploring how to support additional execution models such as VMs and functions-as-a-service. However, using our Pulumi provider, it is possible to combine Defang services with other native AWS resources. + +### Can I access AWS storage services such as S3 or database services such as RDS? How? + +- Yes! You can access AWS services in the AWS Dashboard as you normally would when you are [deploying to your AWS account](../providers/aws) using Defang. In fact, you can access whatever other resources exist in the cloud account you are using for [Defang BYOC](../concepts/defang-byoc.md). + +### Do you plan to support other clouds? + +- While we currently support [AWS](../concepts/defang-byoc#aws) for production and [DigitalOcean](../concepts/defang-byoc#digitalocean) in preview, we plan to support other clouds in future releases, such as [GCP](../providers/gcp.md) and [Azure](../providers/azure.md). + +## Deployment Process + +### Can I run production apps with Defang? + +- Yes! Defang makes it easy to deploy your app on production-ready infrastructure in your own cloud account. For example, you can deploy your app to AWS with `defang up --provider=aws --mode=production`. Check out your preferred cloud provider on [Defang BYOC](../concepts/defang-byoc.md). + +### Does Defang support blue/green deployments? + +- Defang does not currently support Blue/Green deploys, but it does support rolling updates with the `production` deployment mode. `defang up --mode=production`. + +### Does Defang support rolling deployments? + +- Yes! Defang supports rolling updates with the `production` deployment mode. `defang up --mode=production`. + +### 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. + +### Can I deploy multiple services at once? + +- Yes! You can deploy multiple services at once by defining them in a single compose.yaml file. When you run `defang compose up`, Defang will deploy all the services defined in the file at once. + +### Can I deploy a service that depends on another service? + +- Defang does not currently support service dependencies. All services will be deployed simultaneously. Defang will however run multiple healthchecks before marking a service as healthy and spinning down any previously deployed services when using the `production` deployment mode. + +## Troubleshooting + +### I'm having trouble running the binary on my Mac. What should I do? + +- MacOS users will need to allow the binary to run due to security settings: + 1. Attempt to run the binary. You'll see a security prompt preventing you from running it. + 2. Go to System Preferences > Privacy & Security > General. + 3. In the 'Allow applications downloaded from:' section, you should see a message about Defang being blocked. Click 'Open Anyway'. + 4. Alternatively, select the option "App Store and identified developers" to allow all applications from the App Store and identified developers to run. + +### I'm getting a warning/error. What does it mean? +- See the Common Warnings and Errors page. + From 94bb70ede71f01b611ead9361ad8d7a7736b27bd Mon Sep 17 00:00:00 2001 From: commit111 Date: Mon, 2 Dec 2024 10:29:07 -0800 Subject: [PATCH 18/22] add correct hyperlinks --- docs/faq/faq2.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/faq/faq2.md b/docs/faq/faq2.md index 1e37005ea..4e200f513 100644 --- a/docs/faq/faq2.md +++ b/docs/faq/faq2.md @@ -69,5 +69,5 @@ import {Button, ButtonGroup, FormGroup, FormLabel} from "@mui/material" 4. Alternatively, select the option "App Store and identified developers" to allow all applications from the App Store and identified developers to run. ### I'm getting a warning/error. What does it mean? -- See the Common Warnings and Errors page. +- See the [Common Error Messages](./warnings-errors.md) page. From 0bc42e1b5fd8c9b26904a1e7e21d3df97b2db05d Mon Sep 17 00:00:00 2001 From: commit111 Date: Mon, 2 Dec 2024 10:36:28 -0800 Subject: [PATCH 19/22] rename faq2 to questions --- docs/faq/faq2.md | 73 ------------------------------------------- docs/faq/questions.md | 2 ++ 2 files changed, 2 insertions(+), 73 deletions(-) delete mode 100644 docs/faq/faq2.md diff --git a/docs/faq/faq2.md b/docs/faq/faq2.md deleted file mode 100644 index 4e200f513..000000000 --- a/docs/faq/faq2.md +++ /dev/null @@ -1,73 +0,0 @@ ---- -sidebar_position: 600 -title: Frequently Asked Questions -description: Frequently asked questions about Defang. ---- -import {Button, ButtonGroup, FormGroup, FormLabel} from "@mui/material" - -# Frequently Asked Questions (FAQ) - -## Deployment and Infrastructure -### Which cloud/region is the app being deployed to? - -- In the [Defang Playground](../concepts/defang-playground.md), the app is deployed to AWS `us-west-2`. In the [Defang BYOC](../concepts/defang-byoc.md) model, the region is determined by your [Defang BYOC Provider](/docs/category/providers) settings. - -### Can I bring my own AWS or other cloud account? - -- Yes! Defang makes it easy to deploy your application to your own cloud account. Please check out the [Defang BYOC](../concepts/defang-byoc.md) documentation for more information. - -### On AWS, can I deploy to services such as EC2, EKS, or Lambda? - -- The current release includes support for containers only, deployed to ECS. We are still exploring how to support additional execution models such as VMs and functions-as-a-service. However, using our Pulumi provider, it is possible to combine Defang services with other native AWS resources. - -### Can I access AWS storage services such as S3 or database services such as RDS? How? - -- Yes! You can access AWS services in the AWS Dashboard as you normally would when you are [deploying to your AWS account](../providers/aws) using Defang. In fact, you can access whatever other resources exist in the cloud account you are using for [Defang BYOC](../concepts/defang-byoc.md). - -### Do you plan to support other clouds? - -- While we currently support [AWS](../concepts/defang-byoc#aws) for production and [DigitalOcean](../concepts/defang-byoc#digitalocean) in preview, we plan to support other clouds in future releases, such as [GCP](../providers/gcp.md) and [Azure](../providers/azure.md). - -## Deployment Process - -### Can I run production apps with Defang? - -- Yes! Defang makes it easy to deploy your app on production-ready infrastructure in your own cloud account. For example, you can deploy your app to AWS with `defang up --provider=aws --mode=production`. Check out your preferred cloud provider on [Defang BYOC](../concepts/defang-byoc.md). - -### Does Defang support blue/green deployments? - -- Defang does not currently support Blue/Green deploys, but it does support rolling updates with the `production` deployment mode. `defang up --mode=production`. - -### Does Defang support rolling deployments? - -- Yes! Defang supports rolling updates with the `production` deployment mode. `defang up --mode=production`. - -### 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. - -### Can I deploy multiple services at once? - -- Yes! You can deploy multiple services at once by defining them in a single compose.yaml file. When you run `defang compose up`, Defang will deploy all the services defined in the file at once. - -### Can I deploy a service that depends on another service? - -- Defang does not currently support service dependencies. All services will be deployed simultaneously. Defang will however run multiple healthchecks before marking a service as healthy and spinning down any previously deployed services when using the `production` deployment mode. - -## Troubleshooting - -### I'm having trouble running the binary on my Mac. What should I do? - -- MacOS users will need to allow the binary to run due to security settings: - 1. Attempt to run the binary. You'll see a security prompt preventing you from running it. - 2. Go to System Preferences > Privacy & Security > General. - 3. In the 'Allow applications downloaded from:' section, you should see a message about Defang being blocked. Click 'Open Anyway'. - 4. Alternatively, select the option "App Store and identified developers" to allow all applications from the App Store and identified developers to run. - -### I'm getting a warning/error. What does it mean? -- See the [Common Error Messages](./warnings-errors.md) page. - diff --git a/docs/faq/questions.md b/docs/faq/questions.md index e5db4143a..c219a8550 100644 --- a/docs/faq/questions.md +++ b/docs/faq/questions.md @@ -8,6 +8,7 @@ import {Button, ButtonGroup, FormGroup, FormLabel} from "@mui/material" # Frequently Asked Questions (FAQ) ## Deployment and Infrastructure + ### Which cloud/region is the app being deployed to? - In the [Defang Playground](../concepts/defang-playground.md), the app is deployed to AWS `us-west-2`. In the [Defang BYOC](../concepts/defang-byoc.md) model, the region is determined by your [Defang BYOC Provider](/docs/category/providers) settings. @@ -80,5 +81,6 @@ import {Button, ButtonGroup, FormGroup, FormLabel} from "@mui/material" 4. Alternatively, select the option "App Store and identified developers" to allow all applications from the App Store and identified developers to run. ### I'm getting a warning/error. What does it mean? + - Please see the [Common Error Messages](./warnings-errors.md) page. From 4002ef64bd6335a99ad2a83cd6b3dede109e0f52 Mon Sep 17 00:00:00 2001 From: commit111 Date: Mon, 2 Dec 2024 15:00:07 -0800 Subject: [PATCH 20/22] restored old faq for merge conflict --- docs/faq.md | 190 ++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 190 insertions(+) create mode 100644 docs/faq.md diff --git a/docs/faq.md b/docs/faq.md new file mode 100644 index 000000000..ed2fa9cd4 --- /dev/null +++ b/docs/faq.md @@ -0,0 +1,190 @@ +--- +sidebar_position: 600 +title: FAQ +description: Frequently asked questions about Defang. +--- + + +# FAQ + +### Which cloud/region is the app being deployed to? + +- In the [Defang Playground](./concepts/defang-playground.md) the app is deployed to AWS `us-west-2`. In the [Defang BYOC](./concepts/defang-byoc.md) model, the region is determined by your [Defang BYOC Provider](/docs/category/providers) settings. + +### Can I bring my own AWS or other cloud account? + +- Yes! Defang makes it easy to deploy your application to your own cloud account. Please check out the [Defang BYOC](./concepts/defang-byoc.md) documentation for more information. + +### On AWS, can I deploy to services such as EC2, EKS, or Lambda? + +- The current release includes support for containers only, deployed to ECS. We are still exploring how to support additional execution models such as VMs and functions-as-a-service. However, using our Pulumi provider, it is possible to combine Defang services with other native AWS resources. + +### Can I access AWS storage services such as S3 or database services such as RDS? How? + +- Yes, you can access AWS services in the AWS Dashboard as you normally would when you are [deploying to your AWS account](./providers/aws) using Defang. In fact, you can access whatever other resources exist in the cloud account you are using for [Defang BYOC](./concepts/defang-byoc.md). + +### Can I run production apps with Defang? + +- Yes! Defang makes it easy to deploy your app on production-ready infrastructure in your own cloud account. For example, you can deploy your app to AWS with `defang up --provider=aws --mode=production`. Check out your preferred cloud provider on [Defang BYOC](./concepts/defang-byoc.md). + +### Does Defang support blue/green deployments? + +- Defang does not currently support Blue/Green deploys, but it does support rolling updates with the `production` deployment mode. `defang up --mode=production`. + +### Does Defang support rolling deployments? + +- Yes! Defang supports rolling updates with the `production` deployment mode. `defang up --mode=production`. + +### 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. + +### Can I deploy multiple services at once? + +- Yes! You can deploy multiple services at once by defining them in a single compose.yaml file. When you run `defang compose up`, Defang will deploy all the services defined in the file at once. + +### Can I deploy a service that depends on another service? + +- Defang does not currently support service dependencies. All services will be deployed simultaneously. Defang will however run multiple healthchecks before marking a service as healthy and spinning down any previously deployed services when using the `production` deployment mode. + +### Do you plan to support other clouds? + +- While we currently support [AWS](./concepts/defang-byoc#aws) for production and [DigitalOcean](./concepts/defang-byoc#digitalocean) in preview, we plan to support other clouds in future releases, such as [GCP](./providers/gcp.md) and [Azure](./providers/azure.md). + +### I'm having trouble running the binary on my Mac. What should I do? + +- MacOS users will need to allow the binary to run due to security settings: + 1. Attempt to run the binary. You'll see a security prompt preventing you from running it. + 2. Go to System Preferences > Privacy & Security > General. + 3. In the 'Allow applications downloaded from:' section, you should see a message about Defang being blocked. Click 'Open Anyway'. + 4. Alternatively, select the option "App Store and identified developers" to allow all applications from the App Store and identified developers to run. + +## Warnings + +### "The folder is not empty. Files may be overwritten." +- This message is displayed when you run `defang generate` and the target folder is not empty. If you proceed, Defang will overwrite any existing files with the same name. If you want to keep the existing files, you should move them to a different folder before running `defang generate` or pick a different target folder. + +### "environment variable not found" +- This message is displayed when you run `defang compose up` and the Compose file references an environment variable that is not set. If you proceed, the environment variable will be empty in the container. If you want to set the environment variable, you should set it in the environment where you run `defang compose up`. + +### "Unsupported platform" +- This message is displayed when you run `defang compose up` and the Compose file references a platform that is not supported by Defang. + +### "not logged in" +- This message is displayed when you run `defang compose config` but you are not logged in. The displayed configuration will be incomplete. If you want to see the complete configuration, you should log in first using `defang login`. + +### "No port mode was specified; assuming 'host'" +- This message is displayed when you run `defang compose up` and the Compose file declares a `port` that does not specify a port `mode`. By default, Defang will keep the port private. If you want to expose the port to the public internet, you should specify the `mode` as `ingress`: +``` +services: + service1: + … + ports: + - target: 80 + mode: ingress +``` + +### "Published ports are not supported in ingress mode; assuming 'host'" +- This message is displayed when you run `defang compose up` and the Compose file declares a `port` with `mode` set to `ingress` and `published` set to a port number. Defang does not support published ports in ingress mode. If you want to expose the port to the public internet, you should specify the `mode` as `ingress` and remove the `published` setting. + +### "TCP ingress is not supported; assuming HTTP" +- This message is displayed when you run `defang compose up` and the Compose file declares a `port` with `mode` set to `ingress` and `protocol` set to `tcp`. Defang does not support arbitrary TCP ingress and will assume the port is used for HTTP traffic. To silence the warning, remove the `protocol` setting. + +### "unsupported compose directive" +- This message is displayed when you run `defang compose up` and the Compose file declares a directive that is not supported by Defang. The deployment will continue, but the unsupported directive will be ignored, which may cause unexpected behavior. + +### "no reservations specified; using limits as reservations" +- This message is displayed when you run `defang compose up` and the Compose file declares a `resource` with `limits` but no `reservations`. Defang will use the `limits` as `reservations` to ensure the container has enough resources. Specify `reservations` if you want to silence the warning or reserve a different amount of resources: +``` +services: + service1: + … + deploy: + resources: + reservations: + cpus: 0.5 + memory: 512MB +``` + +### "ingress port without healthcheck defaults to GET / HTTP/1.1" +- This message is displayed when you run `defang compose up` and the Compose file declares an `ingress` with a `port` but no `healthcheck`. Defang will assume the default healthcheck of `GET / HTTP/1.1` to ensure the port is healthy. Specify a `healthcheck` if you want to silence the warning or use a different healthcheck: +``` +services: + service1: + … + deploy: + healthcheck: + test: ["CMD", "curl", "-f", "http://localhost:80/health"] +``` + +### "missing memory reservation; specify deploy.resources.reservations.memory to avoid out-of-memory errors" +- This message is displayed when you run `defang compose up` and the Compose file doesn't specify a `memory` reservation. If available, Defang will use the `memory` limit as the `memory` reservation. Specify a `memory` reservation if you want to silence the warning or reserve a different amount of memory: +``` +services: + service1: + … + deploy: + resources: + reservations: + memory: 512MB +``` + +### "The build context contains more than 10 files" +- This message is displayed when you run `defang compose up` and the Compose file declares a `build` with a `context` that contains more than 10 files. Ensure the context refers to the correct folder. Defang will use the `context` as is, but you may experience slow build times. If you want to speed up the build, you should reduce the number of files in the `context`. + +### "AWS provider was selected, but AWS environment variables are not set" +- This message is displayed when you run `defang compose up` with the `--provider=aws` but none of the AWS environment variables were set. If you proceed, the deployment might fail, unless you have defined defined `default` credentials in the AWS configuration files or are running on an AWS instance. + +### "Using Defang provider, but AWS environment variables were detected" +- This message is displayed when you run `defang compose up` with the `--provider=defang` but AWS environment variables were detected. The AWS environment variables will be ignored. + +## Errors + +### "Stack:… is in UPDATE_COMPLETE_CLEANUP_IN_PROGRESS state and cannot be updated" +- This happens if different version of the Defang CLI are used with the same AWS account. Each version one will try to update the CD stack to its version, back and forth. Make sure that all users have the same version of the CLI. Check the CLI version using `defang version`. + +### "invalid healthcheck: ingress ports require an HTTP healthcheck on `localhost`. + +- This message is displayed when `defang compose up` tries to deploy a service with an "ingress" port, if the service does not have a `healthcheck` which mentions `localhost`. Defang routes a load balancer to your service's ingress ports, and the loadbalancer needs to be able to check the health of the service. To solve this issue, ask yourself these two questions: + +1. Should my service be public? It's common to declare your container's ports using the Compose file "shorthand" syntax (`1234:1234`). This syntax can be understood as `[HOST:]CONTAINER`. If your service is not intended to be public, you do not need to declare a HOST port. For example: + + ```diff + services: + my-service: + image: my-image + ports: + - - "1234:1234" + + - "1234" + ``` +2. Does my healthcheck include the string `localhost`? It is very common to define a healthcheck by using `curl` or `wget` to make a request to `localhost`. So common, in fact, that defang will look for the string `localhost` in your healthcheck definition. For example, this healthcheck is valid: + + ```yaml + healthcheck: + test: ["CMD", "curl", "-f", "http://localhost:1234/health"] + ``` + + This healthcheck is not valid for `ingress` ports: + + ```yaml + healthcheck: + test: ["CMD", "./my-healthcheck"] + ``` + +### The build aborted with OutOfMemoryError: Container killed due to memory usage + +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 +``` From 297243b4a3c8a885c283eaa995b5f81d39f817ef Mon Sep 17 00:00:00 2001 From: commit111 Date: Mon, 2 Dec 2024 17:10:05 -0800 Subject: [PATCH 21/22] delete old faq file --- docs/faq.md | 190 ---------------------------------------------------- 1 file changed, 190 deletions(-) delete mode 100644 docs/faq.md diff --git a/docs/faq.md b/docs/faq.md deleted file mode 100644 index ed2fa9cd4..000000000 --- a/docs/faq.md +++ /dev/null @@ -1,190 +0,0 @@ ---- -sidebar_position: 600 -title: FAQ -description: Frequently asked questions about Defang. ---- - - -# FAQ - -### Which cloud/region is the app being deployed to? - -- In the [Defang Playground](./concepts/defang-playground.md) the app is deployed to AWS `us-west-2`. In the [Defang BYOC](./concepts/defang-byoc.md) model, the region is determined by your [Defang BYOC Provider](/docs/category/providers) settings. - -### Can I bring my own AWS or other cloud account? - -- Yes! Defang makes it easy to deploy your application to your own cloud account. Please check out the [Defang BYOC](./concepts/defang-byoc.md) documentation for more information. - -### On AWS, can I deploy to services such as EC2, EKS, or Lambda? - -- The current release includes support for containers only, deployed to ECS. We are still exploring how to support additional execution models such as VMs and functions-as-a-service. However, using our Pulumi provider, it is possible to combine Defang services with other native AWS resources. - -### Can I access AWS storage services such as S3 or database services such as RDS? How? - -- Yes, you can access AWS services in the AWS Dashboard as you normally would when you are [deploying to your AWS account](./providers/aws) using Defang. In fact, you can access whatever other resources exist in the cloud account you are using for [Defang BYOC](./concepts/defang-byoc.md). - -### Can I run production apps with Defang? - -- Yes! Defang makes it easy to deploy your app on production-ready infrastructure in your own cloud account. For example, you can deploy your app to AWS with `defang up --provider=aws --mode=production`. Check out your preferred cloud provider on [Defang BYOC](./concepts/defang-byoc.md). - -### Does Defang support blue/green deployments? - -- Defang does not currently support Blue/Green deploys, but it does support rolling updates with the `production` deployment mode. `defang up --mode=production`. - -### Does Defang support rolling deployments? - -- Yes! Defang supports rolling updates with the `production` deployment mode. `defang up --mode=production`. - -### 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. - -### Can I deploy multiple services at once? - -- Yes! You can deploy multiple services at once by defining them in a single compose.yaml file. When you run `defang compose up`, Defang will deploy all the services defined in the file at once. - -### Can I deploy a service that depends on another service? - -- Defang does not currently support service dependencies. All services will be deployed simultaneously. Defang will however run multiple healthchecks before marking a service as healthy and spinning down any previously deployed services when using the `production` deployment mode. - -### Do you plan to support other clouds? - -- While we currently support [AWS](./concepts/defang-byoc#aws) for production and [DigitalOcean](./concepts/defang-byoc#digitalocean) in preview, we plan to support other clouds in future releases, such as [GCP](./providers/gcp.md) and [Azure](./providers/azure.md). - -### I'm having trouble running the binary on my Mac. What should I do? - -- MacOS users will need to allow the binary to run due to security settings: - 1. Attempt to run the binary. You'll see a security prompt preventing you from running it. - 2. Go to System Preferences > Privacy & Security > General. - 3. In the 'Allow applications downloaded from:' section, you should see a message about Defang being blocked. Click 'Open Anyway'. - 4. Alternatively, select the option "App Store and identified developers" to allow all applications from the App Store and identified developers to run. - -## Warnings - -### "The folder is not empty. Files may be overwritten." -- This message is displayed when you run `defang generate` and the target folder is not empty. If you proceed, Defang will overwrite any existing files with the same name. If you want to keep the existing files, you should move them to a different folder before running `defang generate` or pick a different target folder. - -### "environment variable not found" -- This message is displayed when you run `defang compose up` and the Compose file references an environment variable that is not set. If you proceed, the environment variable will be empty in the container. If you want to set the environment variable, you should set it in the environment where you run `defang compose up`. - -### "Unsupported platform" -- This message is displayed when you run `defang compose up` and the Compose file references a platform that is not supported by Defang. - -### "not logged in" -- This message is displayed when you run `defang compose config` but you are not logged in. The displayed configuration will be incomplete. If you want to see the complete configuration, you should log in first using `defang login`. - -### "No port mode was specified; assuming 'host'" -- This message is displayed when you run `defang compose up` and the Compose file declares a `port` that does not specify a port `mode`. By default, Defang will keep the port private. If you want to expose the port to the public internet, you should specify the `mode` as `ingress`: -``` -services: - service1: - … - ports: - - target: 80 - mode: ingress -``` - -### "Published ports are not supported in ingress mode; assuming 'host'" -- This message is displayed when you run `defang compose up` and the Compose file declares a `port` with `mode` set to `ingress` and `published` set to a port number. Defang does not support published ports in ingress mode. If you want to expose the port to the public internet, you should specify the `mode` as `ingress` and remove the `published` setting. - -### "TCP ingress is not supported; assuming HTTP" -- This message is displayed when you run `defang compose up` and the Compose file declares a `port` with `mode` set to `ingress` and `protocol` set to `tcp`. Defang does not support arbitrary TCP ingress and will assume the port is used for HTTP traffic. To silence the warning, remove the `protocol` setting. - -### "unsupported compose directive" -- This message is displayed when you run `defang compose up` and the Compose file declares a directive that is not supported by Defang. The deployment will continue, but the unsupported directive will be ignored, which may cause unexpected behavior. - -### "no reservations specified; using limits as reservations" -- This message is displayed when you run `defang compose up` and the Compose file declares a `resource` with `limits` but no `reservations`. Defang will use the `limits` as `reservations` to ensure the container has enough resources. Specify `reservations` if you want to silence the warning or reserve a different amount of resources: -``` -services: - service1: - … - deploy: - resources: - reservations: - cpus: 0.5 - memory: 512MB -``` - -### "ingress port without healthcheck defaults to GET / HTTP/1.1" -- This message is displayed when you run `defang compose up` and the Compose file declares an `ingress` with a `port` but no `healthcheck`. Defang will assume the default healthcheck of `GET / HTTP/1.1` to ensure the port is healthy. Specify a `healthcheck` if you want to silence the warning or use a different healthcheck: -``` -services: - service1: - … - deploy: - healthcheck: - test: ["CMD", "curl", "-f", "http://localhost:80/health"] -``` - -### "missing memory reservation; specify deploy.resources.reservations.memory to avoid out-of-memory errors" -- This message is displayed when you run `defang compose up` and the Compose file doesn't specify a `memory` reservation. If available, Defang will use the `memory` limit as the `memory` reservation. Specify a `memory` reservation if you want to silence the warning or reserve a different amount of memory: -``` -services: - service1: - … - deploy: - resources: - reservations: - memory: 512MB -``` - -### "The build context contains more than 10 files" -- This message is displayed when you run `defang compose up` and the Compose file declares a `build` with a `context` that contains more than 10 files. Ensure the context refers to the correct folder. Defang will use the `context` as is, but you may experience slow build times. If you want to speed up the build, you should reduce the number of files in the `context`. - -### "AWS provider was selected, but AWS environment variables are not set" -- This message is displayed when you run `defang compose up` with the `--provider=aws` but none of the AWS environment variables were set. If you proceed, the deployment might fail, unless you have defined defined `default` credentials in the AWS configuration files or are running on an AWS instance. - -### "Using Defang provider, but AWS environment variables were detected" -- This message is displayed when you run `defang compose up` with the `--provider=defang` but AWS environment variables were detected. The AWS environment variables will be ignored. - -## Errors - -### "Stack:… is in UPDATE_COMPLETE_CLEANUP_IN_PROGRESS state and cannot be updated" -- This happens if different version of the Defang CLI are used with the same AWS account. Each version one will try to update the CD stack to its version, back and forth. Make sure that all users have the same version of the CLI. Check the CLI version using `defang version`. - -### "invalid healthcheck: ingress ports require an HTTP healthcheck on `localhost`. - -- This message is displayed when `defang compose up` tries to deploy a service with an "ingress" port, if the service does not have a `healthcheck` which mentions `localhost`. Defang routes a load balancer to your service's ingress ports, and the loadbalancer needs to be able to check the health of the service. To solve this issue, ask yourself these two questions: - -1. Should my service be public? It's common to declare your container's ports using the Compose file "shorthand" syntax (`1234:1234`). This syntax can be understood as `[HOST:]CONTAINER`. If your service is not intended to be public, you do not need to declare a HOST port. For example: - - ```diff - services: - my-service: - image: my-image - ports: - - - "1234:1234" - + - "1234" - ``` -2. Does my healthcheck include the string `localhost`? It is very common to define a healthcheck by using `curl` or `wget` to make a request to `localhost`. So common, in fact, that defang will look for the string `localhost` in your healthcheck definition. For example, this healthcheck is valid: - - ```yaml - healthcheck: - test: ["CMD", "curl", "-f", "http://localhost:1234/health"] - ``` - - This healthcheck is not valid for `ingress` ports: - - ```yaml - healthcheck: - test: ["CMD", "./my-healthcheck"] - ``` - -### The build aborted with OutOfMemoryError: Container killed due to memory usage - -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 -``` From 1860a2bb6197b0a1de4fc5c57b5f2b8f74d23d2d Mon Sep 17 00:00:00 2001 From: commit111 Date: Mon, 2 Dec 2024 17:15:38 -0800 Subject: [PATCH 22/22] restore faq file --- docs/faq.md | 190 ++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 190 insertions(+) create mode 100644 docs/faq.md diff --git a/docs/faq.md b/docs/faq.md new file mode 100644 index 000000000..c399db4fa --- /dev/null +++ b/docs/faq.md @@ -0,0 +1,190 @@ +--- +sidebar_position: 600 +title: FAQ +description: Frequently asked questions about Defang. +--- + + +# FAQ + +### Which cloud/region is the app being deployed to? + +- In the [Defang Playground](./concepts/defang-playground.md) the app is deployed to AWS `us-west-2`. In the [Defang BYOC](./concepts/defang-byoc.md) model, the region is determined by your [Defang BYOC Provider](/docs/category/providers) settings. + +### Can I bring my own AWS or other cloud account? + +- Yes! Defang makes it easy to deploy your application to your own cloud account. Please check out the [Defang BYOC](./concepts/defang-byoc.md) documentation for more information. + +### On AWS, can I deploy to services such as EC2, EKS, or Lambda? + +- The current release includes support for containers only, deployed to ECS. We are still exploring how to support additional execution models such as VMs and functions-as-a-service. However, using our Pulumi provider, it is possible to combine Defang services with other native AWS resources. + +### Can I access AWS storage services such as S3 or database services such as RDS? How? + +- Yes, you can access AWS services in the AWS Dashboard as you normally would when you are [deploying to your AWS account](./providers/aws) using Defang. In fact, you can access whatever other resources exist in the cloud account you are using for [Defang BYOC](./concepts/defang-byoc.md). + +### Can I run production apps with Defang? + +- Yes! Defang makes it easy to deploy your app on production-ready infrastructure in your own cloud account. For example, you can deploy your app to AWS with `defang up --provider=aws --mode=production`. Check out your preferred cloud provider on [Defang BYOC](./concepts/defang-byoc.md). + +### Does Defang support blue/green deployments? + +- Defang does not currently support Blue/Green deploys, but it does support rolling updates with the `production` deployment mode. `defang up --mode=production`. + +### Does Defang support rolling deployments? + +- Yes! Defang supports rolling updates with the `production` deployment mode. `defang up --mode=production`. + +### 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. + +### Can I deploy multiple services at once? + +- Yes! You can deploy multiple services at once by defining them in a single compose.yaml file. When you run `defang compose up`, Defang will deploy all the services defined in the file at once. + +### Can I deploy a service that depends on another service? + +- Defang does not currently support service dependencies. All services will be deployed simultaneously. Defang will however run multiple healthchecks before marking a service as healthy and spinning down any previously deployed services when using the `production` deployment mode. + +### Do you plan to support other clouds? + +- While we currently support [AWS](./concepts/defang-byoc#aws) for production and [DigitalOcean](./concepts/defang-byoc#digitalocean) in preview, we plan to support other clouds in future releases, such as [GCP](./providers/gcp.md) and [Azure](./providers/azure.md). + +### I'm having trouble running the binary on my Mac. What should I do? + +- MacOS users will need to allow the binary to run due to security settings: + 1. Attempt to run the binary. You'll see a security prompt preventing you from running it. + 2. Go to System Preferences > Privacy & Security > General. + 3. In the 'Allow applications downloaded from:' section, you should see a message about Defang being blocked. Click 'Open Anyway'. + 4. Alternatively, select the option "App Store and identified developers" to allow all applications from the App Store and identified developers to run. + +## Warnings + +### "The folder is not empty. Files may be overwritten." +- This message is displayed when you run `defang generate` and the target folder is not empty. If you proceed, Defang will overwrite any existing files with the same name. If you want to keep the existing files, you should move them to a different folder before running `defang generate` or pick a different target folder. + +### "environment variable not found" +- This message is displayed when you run `defang compose up` and the Compose file references an environment variable that is not set. If you proceed, the environment variable will be empty in the container. If you want to set the environment variable, you should set it in the environment where you run `defang compose up`. + +### "Unsupported platform" +- This message is displayed when you run `defang compose up` and the Compose file references a platform that is not supported by Defang. + +### "not logged in" +- This message is displayed when you run `defang compose config` but you are not logged in. The displayed configuration will be incomplete. If you want to see the complete configuration, you should log in first using `defang login`. + +### "No port mode was specified; assuming 'host'" +- This message is displayed when you run `defang compose up` and the Compose file declares a `port` that does not specify a port `mode`. By default, Defang will keep the port private. If you want to expose the port to the public internet, you should specify the `mode` as `ingress`: +``` +services: + service1: + … + ports: + - target: 80 + mode: ingress +``` + +### "Published ports are not supported in ingress mode; assuming 'host'" +- This message is displayed when you run `defang compose up` and the Compose file declares a `port` with `mode` set to `ingress` and `published` set to a port number. Defang does not support published ports in ingress mode. If you want to expose the port to the public internet, you should specify the `mode` as `ingress` and remove the `published` setting. + +### "TCP ingress is not supported; assuming HTTP" +- This message is displayed when you run `defang compose up` and the Compose file declares a `port` with `mode` set to `ingress` and `protocol` set to `tcp`. Defang does not support arbitrary TCP ingress and will assume the port is used for HTTP traffic. To silence the warning, remove the `protocol` setting. + +### "unsupported compose directive" +- This message is displayed when you run `defang compose up` and the Compose file declares a directive that is not supported by Defang. The deployment will continue, but the unsupported directive will be ignored, which may cause unexpected behavior. + +### "no reservations specified; using limits as reservations" +- This message is displayed when you run `defang compose up` and the Compose file declares a `resource` with `limits` but no `reservations`. Defang will use the `limits` as `reservations` to ensure the container has enough resources. Specify `reservations` if you want to silence the warning or reserve a different amount of resources: +``` +services: + service1: + … + deploy: + resources: + reservations: + cpus: 0.5 + memory: 512MB +``` + +### "ingress port without healthcheck defaults to GET / HTTP/1.1" +- This message is displayed when you run `defang compose up` and the Compose file declares an `ingress` with a `port` but no `healthcheck`. Defang will assume the default healthcheck of `GET / HTTP/1.1` to ensure the port is healthy. Specify a `healthcheck` if you want to silence the warning or use a different healthcheck: +``` +services: + service1: + … + deploy: + healthcheck: + test: ["CMD", "curl", "-f", "http://localhost:80/health"] +``` + +### "missing memory reservation; specify deploy.resources.reservations.memory to avoid out-of-memory errors" +- This message is displayed when you run `defang compose up` and the Compose file doesn't specify a `memory` reservation. If available, Defang will use the `memory` limit as the `memory` reservation. Specify a `memory` reservation if you want to silence the warning or reserve a different amount of memory: +``` +services: + service1: + … + deploy: + resources: + reservations: + memory: 512MB +``` + +### "The build context contains more than 10 files" +- This message is displayed when you run `defang compose up` and the Compose file declares a `build` with a `context` that contains more than 10 files. Ensure the context refers to the correct folder. Defang will use the `context` as is, but you may experience slow build times. If you want to speed up the build, you should reduce the number of files in the `context`. + +### "AWS provider was selected, but AWS environment variables are not set" +- This message is displayed when you run `defang compose up` with the `--provider=aws` but none of the AWS environment variables were set. If you proceed, the deployment might fail, unless you have defined defined `default` credentials in the AWS configuration files or are running on an AWS instance. + +### "Using Defang provider, but AWS environment variables were detected" +- This message is displayed when you run `defang compose up` with the `--provider=defang` but AWS environment variables were detected. The AWS environment variables will be ignored. + +## Errors + +### "Stack:… is in UPDATE_COMPLETE_CLEANUP_IN_PROGRESS state and cannot be updated" +- This happens if different version of the Defang CLI are used with the same AWS account. Each version one will try to update the CD stack to its version, back and forth. Make sure that all users have the same version of the CLI. Check the CLI version using `defang version`. + +### "invalid healthcheck: ingress ports require an HTTP healthcheck on `localhost`. + +- This message is displayed when `defang compose up` tries to deploy a service with an "ingress" port, if the service does not have a `healthcheck` which mentions `localhost`. Defang routes a load balancer to your service's ingress ports, and the loadbalancer needs to be able to check the health of the service. To solve this issue, ask yourself these two questions: + +1. Should my service be public? It's common to declare your container's ports using the Compose file "shorthand" syntax (`1234:1234`). This syntax can be understood as `[HOST:]CONTAINER`. If your service is not intended to be public, you do not need to declare a HOST port. For example: + + ```diff + services: + my-service: + image: my-image + ports: + - - "1234:1234" + + - "1234" + ``` +2. Does my healthcheck include the string `localhost`? It is very common to define a healthcheck by using `curl` or `wget` to make a request to `localhost`. So common, in fact, that Defang will look for the string `localhost` in your healthcheck definition. For example, this healthcheck is valid: + + ```yaml + healthcheck: + test: ["CMD", "curl", "-f", "http://localhost:1234/health"] + ``` + + This healthcheck is not valid for `ingress` ports: + + ```yaml + healthcheck: + test: ["CMD", "./my-healthcheck"] + ``` + +### The build aborted with OutOfMemoryError: Container killed due to memory usage + +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 +```