From 1f2c25f7e71154c6cb30a6474a409a232f72f7d6 Mon Sep 17 00:00:00 2001 From: linda Date: Mon, 23 Dec 2024 14:07:30 -0800 Subject: [PATCH 01/28] clear config explanation --- docs/concepts/configuration.md | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-) diff --git a/docs/concepts/configuration.md b/docs/concepts/configuration.md index 6efdd64bf..0b5076e2d 100644 --- a/docs/concepts/configuration.md +++ b/docs/concepts/configuration.md @@ -19,6 +19,9 @@ defang config set API_KEY You can use sensitive config by specifying them in the `environment` section of a service in a `compose.yaml` file without any value, or by specifying an environment key with a `null` value in your Pulumi code. +Either one of list notation or map notation is acceptable for defining your environment variable(s). See below for an example of each. + +#### With List Notation ```yaml services: service1: @@ -27,9 +30,7 @@ services: - API_KEY ``` -You can also use this syntax: - - +#### With Map Notation ```yaml services: service1: From dad7e65a6c227f25fe3a0d6b6efcaf5c2662b5c9 Mon Sep 17 00:00:00 2001 From: linda Date: Mon, 23 Dec 2024 14:08:10 -0800 Subject: [PATCH 02/28] started outlining possible compose page outline --- docs/concepts/compose-support.md | 37 ++++++++++++++++++++++++++++++++ 1 file changed, 37 insertions(+) create mode 100644 docs/concepts/compose-support.md diff --git a/docs/concepts/compose-support.md b/docs/concepts/compose-support.md new file mode 100644 index 000000000..2dd475c33 --- /dev/null +++ b/docs/concepts/compose-support.md @@ -0,0 +1,37 @@ +--- +title: Compose Support +description: Defang supports many of the properties of the Compose specification. +sidebar_position: 160 +--- + +# Compose Support + +This page outlines what properties of the [Compose specification](https://docs.docker.com/compose/compose-file/) Defang supports when writing a `compose.yaml` file. +For a more general overview of how Defang works with Compose, please see our [Compose](/docs/concepts/compose) page. + +### Supported Compose Properties +|Property | Details +|-|- +|`image` | + +### Optional Compose Properties +|Property | Details +|-|- +|`ports` | If left unspecified, a random port will be chosen. +|`memory` | If left unspecified, will resort to default. +|`environment` | + +### Depreciated Compose Properties +|Property | Details +|-|- +|`version` | This top-level element is no longer needed in the Compose file. Instead, Defang uses the most recent schema supported for parsing the file. + +### Unsupported Compose Properties +|Property | Details +|-|- +|`volume` | Volume mounts are not currently supported by Defang, but will not break the file if included. + + + +### Configuration +You can define sensitive environment variables/configuration for Defang by writing out the variable name and leaving it in as a blank or `null` value in the Compose file. See our [Configuration](/docs/concepts/configuration) page for more. \ No newline at end of file From e67d4d62168bf68a89454b825b89b64057d40f27 Mon Sep 17 00:00:00 2001 From: commit111 Date: Fri, 3 Jan 2025 10:16:29 -0800 Subject: [PATCH 03/28] alternative layout as a list, not a table --- docs/concepts/compose-support.md | 132 ++++++++++++++++++++++++++----- 1 file changed, 111 insertions(+), 21 deletions(-) diff --git a/docs/concepts/compose-support.md b/docs/concepts/compose-support.md index 2dd475c33..96a9452c7 100644 --- a/docs/concepts/compose-support.md +++ b/docs/concepts/compose-support.md @@ -6,32 +6,122 @@ sidebar_position: 160 # Compose Support -This page outlines what properties of the [Compose specification](https://docs.docker.com/compose/compose-file/) Defang supports when writing a `compose.yaml` file. -For a more general overview of how Defang works with Compose, please see our [Compose](/docs/concepts/compose) page. +## Required Compose File +Here is a basic `compose.yaml` file that contains all the required properties for deployment in Defang. -### Supported Compose Properties -|Property | Details -|-|- -|`image` | +```yaml +services: + service-example: + restart: unless-stopped # specify a restart mode + image: nginx:latest # specify an image (or a build, as shown below) + # build: + # context: . + # dockerfile: Dockerfile + ports: + - "8080:80" # specify ports to expose + +``` -### Optional Compose Properties -|Property | Details -|-|- -|`ports` | If left unspecified, a random port will be chosen. -|`memory` | If left unspecified, will resort to default. -|`environment` | +## Compose Service Properties +Here are a list of service-level properties of the [Compose specification](https://docs.docker.com/compose/compose-file/) that Defang supports when writing a `compose.yaml` file. -### Depreciated Compose Properties -|Property | Details -|-|- -|`version` | This top-level element is no longer needed in the Compose file. Instead, Defang uses the most recent schema supported for parsing the file. +:::tip +Service-level means inside your `service`. A service-level property called `build` would look like: +```yaml +service: + build: ... +``` -### Unsupported Compose Properties -|Property | Details -|-|- -|`volume` | Volume mounts are not currently supported by Defang, but will not break the file if included. +Note that in your Compose file, you will need a top-level property called `services` to contain all of your services. For example: +```yaml +services: + service: + build: ... + another-service: + build: ... +``` +::: +### `build` +(Required, unless `image` is defined) + +The build configuration. + +```yaml +build: + context: . + dockerfile: ./Dockerfile +``` + +### `command` +(Optional) + +The command which will be run to start your service. If left out, the command from the docker image will be used. + +```yaml +command: nginx -g 'daemon off;' +``` + +### `environment` +(Optional) + +The environment variables to set. + +```yaml +environment: + MYSQL_ROOT_PASSWORD: example +``` + +### `image` +(Required, unless `build` is defined) + +The image to run. + +```yaml +image: nginx:latest +``` + +### `ports` +(Optional, but required if you want to access the service from outside the container) + +The ports to expose. Can be formatted as `"published:target"`. + +```yaml +ports: + - "8080:80" +``` + +Alternatively, you can use this notation: +```yaml +ports: + - target: 80 + published: 8080 + mode: ingress +``` + +:::info +Defang ignores `published` ports in production. As such, it is common to make `target` and `published` ports the same when using Defang. However, it can be useful to include a `published` port for local development, such as Docker. +::: + +### `restart` +(Required) + +The restart mode for a container. + +```yaml +restart: unless-stopped +``` + +### `version` +(Deprecated) + +The version of the Compose file format being used. This feature is no longer supported and will be ignored by Defang. + +### `volumes` +(Unsupported) + +The volume for a container. This feature is not currently supported by Defang. ### Configuration -You can define sensitive environment variables/configuration for Defang by writing out the variable name and leaving it in as a blank or `null` value in the Compose file. See our [Configuration](/docs/concepts/configuration) page for more. \ No newline at end of file +You can define sensitive environment variables/configuration for Defang by writing out the variable name and leaving it in as a blank or `null` value in the Compose file. See our [Configuration](/docs/concepts/configuration) page for more. From 668a4e0a61ea06b41bbd3b3fba56c5dcd4e4a3ec Mon Sep 17 00:00:00 2001 From: commit111 Date: Sat, 4 Jan 2025 12:29:34 -0800 Subject: [PATCH 04/28] fixes for what is required --- docs/concepts/compose-support.md | 25 ++++++++++++++++++++----- 1 file changed, 20 insertions(+), 5 deletions(-) diff --git a/docs/concepts/compose-support.md b/docs/concepts/compose-support.md index 96a9452c7..2c76465e8 100644 --- a/docs/concepts/compose-support.md +++ b/docs/concepts/compose-support.md @@ -12,13 +12,14 @@ Here is a basic `compose.yaml` file that contains all the required properties fo ```yaml services: service-example: - restart: unless-stopped # specify a restart mode - image: nginx:latest # specify an image (or a build, as shown below) + image: nginx:latest # specify an image (or a build, as shown below — one of the two is required) # build: # context: . # dockerfile: Dockerfile ports: - - "8080:80" # specify ports to expose + - mode: ingress # specify ports to expose + target: 8080 + published: 80 ``` @@ -62,6 +63,20 @@ The command which will be run to start your service. If left out, the command fr command: nginx -g 'daemon off;' ``` +### `deploy` +(Optional) + +The runtime constraints or reuqirements for how your services will be deployed and managed across different environments (e.g. memory reservations, replicas, number of CPUs, etc.). + +```yaml +deploy: + replicas: 2 + reservations: + memory: 256M + cpu: 1 + +``` + ### `environment` (Optional) @@ -104,9 +119,9 @@ Defang ignores `published` ports in production. As such, it is common to make `t ::: ### `restart` -(Required) +(Optional, but highly recommended) -The restart mode for a container. +The restart mode for a container. Defaults to `unless-stopped` unless otherwise specified. ```yaml restart: unless-stopped From 27226b6d5a6c7a9e018e4df06d33964eeab5ae4b Mon Sep 17 00:00:00 2001 From: commit111 Date: Sat, 4 Jan 2025 12:32:39 -0800 Subject: [PATCH 05/28] update ports property --- docs/concepts/compose-support.md | 12 +++--------- 1 file changed, 3 insertions(+), 9 deletions(-) diff --git a/docs/concepts/compose-support.md b/docs/concepts/compose-support.md index 2c76465e8..d43497aaa 100644 --- a/docs/concepts/compose-support.md +++ b/docs/concepts/compose-support.md @@ -99,19 +99,13 @@ image: nginx:latest ### `ports` (Optional, but required if you want to access the service from outside the container) -The ports to expose. Can be formatted as `"published:target"`. +The ports to expose. Mode should be specified as `ingress`. ```yaml ports: - - "8080:80" -``` - -Alternatively, you can use this notation: -```yaml -ports: - - target: 80 + - mode: ingress + target: 80 published: 8080 - mode: ingress ``` :::info From 88cc6b5816da814ce26e92732221bcb22ae4cbdb Mon Sep 17 00:00:00 2001 From: commit111 Date: Sat, 4 Jan 2025 12:40:32 -0800 Subject: [PATCH 06/28] add top level property heading --- docs/concepts/compose-support.md | 20 ++++++++++++++------ 1 file changed, 14 insertions(+), 6 deletions(-) diff --git a/docs/concepts/compose-support.md b/docs/concepts/compose-support.md index d43497aaa..fa8d00838 100644 --- a/docs/concepts/compose-support.md +++ b/docs/concepts/compose-support.md @@ -23,6 +23,19 @@ services: ``` +## Compose Top-level Properties +Here are a list of top-level properties of the [Compose specification](https://docs.docker.com/compose/compose-file/) that Defang supports when writing a `compose.yaml` file. + +### `version` +(Deprecated) + +The version of the Compose file format being used. This feature is no longer supported and will be ignored by Defang. + +### `volumes` +(Unsupported) + +The volume mounts for a container, reusable across services. This feature is not currently supported by Defang. + ## Compose Service Properties Here are a list of service-level properties of the [Compose specification](https://docs.docker.com/compose/compose-file/) that Defang supports when writing a `compose.yaml` file. @@ -121,15 +134,10 @@ The restart mode for a container. Defaults to `unless-stopped` unless otherwise restart: unless-stopped ``` -### `version` -(Deprecated) - -The version of the Compose file format being used. This feature is no longer supported and will be ignored by Defang. - ### `volumes` (Unsupported) -The volume for a container. This feature is not currently supported by Defang. +The volume mounts for a container, specific to a service. This feature is not currently supported by Defang. ### Configuration From f33e5f97cc0456369ede39c9a566c12b85e89776 Mon Sep 17 00:00:00 2001 From: commit111 Date: Sat, 4 Jan 2025 12:48:38 -0800 Subject: [PATCH 07/28] add healthcheck --- docs/concepts/compose-support.md | 17 +++++++++++++++++ 1 file changed, 17 insertions(+) diff --git a/docs/concepts/compose-support.md b/docs/concepts/compose-support.md index fa8d00838..764516369 100644 --- a/docs/concepts/compose-support.md +++ b/docs/concepts/compose-support.md @@ -100,6 +100,23 @@ environment: MYSQL_ROOT_PASSWORD: example ``` +### `healthcheck` +(Optional, but required for healthchecks on services with a published port) + +The healthcheck endpoints for the container. Note that `curl` is commonly used for containers with a `slim` based image, and `wget` is used for containers with an `alpine` based image. + +```yaml +healthcheck: + test: ["CMD", "curl", "-f", "http://localhost:8080/"] +``` + +or + +```yaml +healthcheck: + test: ["CMD", "wget", "--spider", "http://localhost:3000"] +``` + ### `image` (Required, unless `build` is defined) From 74685d8d0a778ea18fccc6b8ed95a298c6f0b6d5 Mon Sep 17 00:00:00 2001 From: commit111 Date: Mon, 6 Jan 2025 13:44:34 -0800 Subject: [PATCH 08/28] adjust examples --- docs/concepts/compose-support.md | 29 +++++++++++++---------------- 1 file changed, 13 insertions(+), 16 deletions(-) diff --git a/docs/concepts/compose-support.md b/docs/concepts/compose-support.md index 764516369..675794e08 100644 --- a/docs/concepts/compose-support.md +++ b/docs/concepts/compose-support.md @@ -11,15 +11,15 @@ Here is a basic `compose.yaml` file that contains all the required properties fo ```yaml services: - service-example: - image: nginx:latest # specify an image (or a build, as shown below — one of the two is required) - # build: - # context: . - # dockerfile: Dockerfile - ports: - - mode: ingress # specify ports to expose - target: 8080 - published: 80 + service-example: + image: nginx:latest # use one of: an image (shown on this line) or a build (shown below) + # build: + # context: . + # dockerfile: Dockerfile + ports: + - mode: ingress # specify ports to expose + target: 8080 + published: 80 ``` @@ -51,8 +51,6 @@ Note that in your Compose file, you will need a top-level property called `servi services: service: build: ... - another-service: - build: ... ``` ::: @@ -83,11 +81,10 @@ The runtime constraints or reuqirements for how your services will be deployed a ```yaml deploy: - replicas: 2 + replicas: 1 reservations: + cpus: '0.5' memory: 256M - cpu: 1 - ``` ### `environment` @@ -107,14 +104,14 @@ The healthcheck endpoints for the container. Note that `curl` is commonly used f ```yaml healthcheck: - test: ["CMD", "curl", "-f", "http://localhost:8080/"] + test: ["CMD", "curl", "-f", "http://localhost:8080/"] ``` or ```yaml healthcheck: - test: ["CMD", "wget", "--spider", "http://localhost:3000"] + test: ["CMD", "wget", "--spider", "http://localhost:3000"] ``` ### `image` From 41dd1f9d9698e5e65fc10c67c0fc0b3df5b448a0 Mon Sep 17 00:00:00 2001 From: commit111 Date: Mon, 6 Jan 2025 13:50:34 -0800 Subject: [PATCH 09/28] fix typo --- docs/concepts/compose-support.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/concepts/compose-support.md b/docs/concepts/compose-support.md index 675794e08..cb6726e25 100644 --- a/docs/concepts/compose-support.md +++ b/docs/concepts/compose-support.md @@ -77,7 +77,7 @@ command: nginx -g 'daemon off;' ### `deploy` (Optional) -The runtime constraints or reuqirements for how your services will be deployed and managed across different environments (e.g. memory reservations, replicas, number of CPUs, etc.). +The runtime constraints or requirements for how your services will be deployed and managed across different environments (e.g. memory reservations, replicas, number of CPUs, etc.). ```yaml deploy: From 39917f9cc08350b94e8015879a68331d35e1e633 Mon Sep 17 00:00:00 2001 From: commit111 Date: Mon, 6 Jan 2025 15:14:10 -0800 Subject: [PATCH 10/28] add more properties --- docs/concepts/compose-support.md | 66 ++++++++++++++++++++++++++++++-- 1 file changed, 62 insertions(+), 4 deletions(-) diff --git a/docs/concepts/compose-support.md b/docs/concepts/compose-support.md index cb6726e25..4edf01171 100644 --- a/docs/concepts/compose-support.md +++ b/docs/concepts/compose-support.md @@ -1,6 +1,6 @@ --- title: Compose Support -description: Defang supports many of the properties of the Compose specification. +description: Defang supports many properties of the Compose specification. sidebar_position: 160 --- @@ -26,16 +26,36 @@ services: ## Compose Top-level Properties Here are a list of top-level properties of the [Compose specification](https://docs.docker.com/compose/compose-file/) that Defang supports when writing a `compose.yaml` file. +### `services` +(Required) + +The services defined in your application. + +```yaml +services: + service: + # add service-level properties here +``` + ### `version` (Deprecated) -The version of the Compose file format being used. This feature is no longer supported and will be ignored by Defang. +The version of the Compose file format being used. This feature is deprecated and will be ignored by Defang. + +```yaml +version: '3' # deprecated +``` ### `volumes` (Unsupported) The volume mounts for a container, reusable across services. This feature is not currently supported by Defang. +```yaml +volumes: # unsupported + db-data: +``` + ## Compose Service Properties Here are a list of service-level properties of the [Compose specification](https://docs.docker.com/compose/compose-file/) that Defang supports when writing a `compose.yaml` file. @@ -87,14 +107,30 @@ deploy: memory: 256M ``` +### `depends_on` +(Unsupported) + +The services that need to be started before this service can run. This feature is currently unsupported by Defang, but can be useful in local developments such as Docker. + +```yaml +depends_on: # unsupported + - db +``` + ### `environment` (Optional) -The environment variables to set. +The environment variables to set. For sensitive environment variables, you can set them with a blank or `null` value. See our page on [Configuration](/docs/concepts/configuration) for more. ```yaml environment: - MYSQL_ROOT_PASSWORD: example + DATABASE_USER: someuser + DATABASE_PASSWORD: # leave blank/null to set config +``` +The above is called *map notation*. You can also use *list notation* as seen below: +```yaml +environment: + - DATABASE_PASSWORD ``` ### `healthcheck` @@ -123,6 +159,24 @@ The image to run. image: nginx:latest ``` +### `networks` +(Optional) + +The network configuration. Can be `public`, where Defang will assign a public IP address, or `private`, in which Defang will not. + +```yaml +networks: + public: +``` + +You can also assign an alias for a network by using `aliases`, as seen below: +```yaml +networks: + public: + aliases: + - app +``` + ### `ports` (Optional, but required if you want to access the service from outside the container) @@ -153,6 +207,10 @@ restart: unless-stopped The volume mounts for a container, specific to a service. This feature is not currently supported by Defang. +```yaml +volumes: # unsupported + - "./backend:/app" +``` ### Configuration You can define sensitive environment variables/configuration for Defang by writing out the variable name and leaving it in as a blank or `null` value in the Compose file. See our [Configuration](/docs/concepts/configuration) page for more. From 10f37b93677499e72ab8cfc6e13403885099ab7e Mon Sep 17 00:00:00 2001 From: commit111 Date: Tue, 7 Jan 2025 10:33:58 -0800 Subject: [PATCH 11/28] update compose support --- docs/concepts/compose-support.md | 32 ++++++++++++++++---------------- 1 file changed, 16 insertions(+), 16 deletions(-) diff --git a/docs/concepts/compose-support.md b/docs/concepts/compose-support.md index 4edf01171..38c04af1f 100644 --- a/docs/concepts/compose-support.md +++ b/docs/concepts/compose-support.md @@ -6,7 +6,7 @@ sidebar_position: 160 # Compose Support -## Required Compose File +## Example of a Compose File Here is a basic `compose.yaml` file that contains all the required properties for deployment in Defang. ```yaml @@ -40,10 +40,10 @@ services: ### `version` (Deprecated) -The version of the Compose file format being used. This feature is deprecated and will be ignored by Defang. +The version of the Compose file format being used. This feature is no longer supported and will be ignored by Defang. ```yaml -version: '3' # deprecated +# version: '3' ``` ### `volumes` @@ -52,11 +52,11 @@ version: '3' # deprecated The volume mounts for a container, reusable across services. This feature is not currently supported by Defang. ```yaml -volumes: # unsupported - db-data: +# volumes: +# db-data: ``` -## Compose Service Properties +## Compose Service-level Properties Here are a list of service-level properties of the [Compose specification](https://docs.docker.com/compose/compose-file/) that Defang supports when writing a `compose.yaml` file. :::tip @@ -113,15 +113,14 @@ deploy: The services that need to be started before this service can run. This feature is currently unsupported by Defang, but can be useful in local developments such as Docker. ```yaml -depends_on: # unsupported - - db +# depends_on: +# - db ``` ### `environment` (Optional) -The environment variables to set. For sensitive environment variables, you can set them with a blank or `null` value. See our page on [Configuration](/docs/concepts/configuration) for more. - +The environment variables to set. For sensitive environment variables, you can set them with a blank or `null` value. ```yaml environment: DATABASE_USER: someuser @@ -133,6 +132,10 @@ environment: - DATABASE_PASSWORD ``` +:::info +After you set sensitive environment variables as blank or `null` values in the `compose.yaml` file, you can securely set their actual value in the Defang CLI. See how Defang handles [Configuration](/docs/concepts/configuration) for more. +::: + ### `healthcheck` (Optional, but required for healthchecks on services with a published port) @@ -162,7 +165,7 @@ image: nginx:latest ### `networks` (Optional) -The network configuration. Can be `public`, where Defang will assign a public IP address, or `private`, in which Defang will not. +The network configuration. Can be `public`, where Defang will assign a public IP address, or `private`, in which Defang will not. To avoid warnings, add this to the `networks` top-level property as well. ```yaml networks: @@ -208,9 +211,6 @@ restart: unless-stopped The volume mounts for a container, specific to a service. This feature is not currently supported by Defang. ```yaml -volumes: # unsupported - - "./backend:/app" +# volumes: +# - "./backend:/app" ``` - -### Configuration -You can define sensitive environment variables/configuration for Defang by writing out the variable name and leaving it in as a blank or `null` value in the Compose file. See our [Configuration](/docs/concepts/configuration) page for more. From 234db8c1692245204db68887b1dc5ee6d100a743 Mon Sep 17 00:00:00 2001 From: commit111 Date: Tue, 7 Jan 2025 10:46:40 -0800 Subject: [PATCH 12/28] update environment --- docs/concepts/compose-support.md | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) diff --git a/docs/concepts/compose-support.md b/docs/concepts/compose-support.md index 38c04af1f..54d28abd3 100644 --- a/docs/concepts/compose-support.md +++ b/docs/concepts/compose-support.md @@ -126,11 +126,14 @@ environment: DATABASE_USER: someuser DATABASE_PASSWORD: # leave blank/null to set config ``` -The above is called *map notation*. You can also use *list notation* as seen below: +:::tip +Alternatively, you can use *list notation* to write your Compose files: ```yaml environment: + - DATABASE_USER=someuser - DATABASE_PASSWORD ``` +::: :::info After you set sensitive environment variables as blank or `null` values in the `compose.yaml` file, you can securely set their actual value in the Defang CLI. See how Defang handles [Configuration](/docs/concepts/configuration) for more. From 77e12967bfdeb2466476cee0c66cfb9bc0c1f0af Mon Sep 17 00:00:00 2001 From: commit111 Date: Tue, 7 Jan 2025 10:55:18 -0800 Subject: [PATCH 13/28] update healthcheck --- docs/concepts/compose-support.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/concepts/compose-support.md b/docs/concepts/compose-support.md index 54d28abd3..d590a593a 100644 --- a/docs/concepts/compose-support.md +++ b/docs/concepts/compose-support.md @@ -136,13 +136,13 @@ environment: ::: :::info -After you set sensitive environment variables as blank or `null` values in the `compose.yaml` file, you can securely set their actual value in the Defang CLI. See how Defang handles [Configuration](/docs/concepts/configuration) for more. +After you set sensitive environment variables as blank or `null` values in the `compose.yaml` file, you can securely set their actual value in the Defang CLI. See our [Configuration page](/docs/concepts/configuration) for more. ::: ### `healthcheck` (Optional, but required for healthchecks on services with a published port) -The healthcheck endpoints for the container. Note that `curl` is commonly used for containers with a `slim` based image, and `wget` is used for containers with an `alpine` based image. +The healthcheck endpoints for the container. Note that `curl` is commonly used for containers with a `slim`-based image, and `wget` is used for containers with an `alpine`-based image. ```yaml healthcheck: @@ -153,7 +153,7 @@ or ```yaml healthcheck: - test: ["CMD", "wget", "--spider", "http://localhost:3000"] + test: ["CMD", "wget", "--spider", "http://localhost:8080/"] ``` ### `image` From 836ac63650338bae342e56a297746a1aff1bc1f0 Mon Sep 17 00:00:00 2001 From: commit111 Date: Tue, 7 Jan 2025 11:00:38 -0800 Subject: [PATCH 14/28] remove tip --- docs/concepts/compose-support.md | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/docs/concepts/compose-support.md b/docs/concepts/compose-support.md index d590a593a..445c839e9 100644 --- a/docs/concepts/compose-support.md +++ b/docs/concepts/compose-support.md @@ -126,14 +126,13 @@ environment: DATABASE_USER: someuser DATABASE_PASSWORD: # leave blank/null to set config ``` -:::tip + Alternatively, you can use *list notation* to write your Compose files: ```yaml environment: - DATABASE_USER=someuser - DATABASE_PASSWORD ``` -::: :::info After you set sensitive environment variables as blank or `null` values in the `compose.yaml` file, you can securely set their actual value in the Defang CLI. See our [Configuration page](/docs/concepts/configuration) for more. From 22ff2bba61604362463334a1e8517601b2d8caf8 Mon Sep 17 00:00:00 2001 From: commit111 Date: Tue, 7 Jan 2025 14:53:10 -0800 Subject: [PATCH 15/28] move compose support to compose page --- docs/concepts/compose-support.md | 218 ---------------------------- docs/concepts/compose.md | 234 ++++++++++++++++++++++++++++--- 2 files changed, 218 insertions(+), 234 deletions(-) delete mode 100644 docs/concepts/compose-support.md diff --git a/docs/concepts/compose-support.md b/docs/concepts/compose-support.md deleted file mode 100644 index 445c839e9..000000000 --- a/docs/concepts/compose-support.md +++ /dev/null @@ -1,218 +0,0 @@ ---- -title: Compose Support -description: Defang supports many properties of the Compose specification. -sidebar_position: 160 ---- - -# Compose Support - -## Example of a Compose File -Here is a basic `compose.yaml` file that contains all the required properties for deployment in Defang. - -```yaml -services: - service-example: - image: nginx:latest # use one of: an image (shown on this line) or a build (shown below) - # build: - # context: . - # dockerfile: Dockerfile - ports: - - mode: ingress # specify ports to expose - target: 8080 - published: 80 - -``` - -## Compose Top-level Properties -Here are a list of top-level properties of the [Compose specification](https://docs.docker.com/compose/compose-file/) that Defang supports when writing a `compose.yaml` file. - -### `services` -(Required) - -The services defined in your application. - -```yaml -services: - service: - # add service-level properties here -``` - -### `version` -(Deprecated) - -The version of the Compose file format being used. This feature is no longer supported and will be ignored by Defang. - -```yaml -# version: '3' -``` - -### `volumes` -(Unsupported) - -The volume mounts for a container, reusable across services. This feature is not currently supported by Defang. - -```yaml -# volumes: -# db-data: -``` - -## Compose Service-level Properties -Here are a list of service-level properties of the [Compose specification](https://docs.docker.com/compose/compose-file/) that Defang supports when writing a `compose.yaml` file. - -:::tip -Service-level means inside your `service`. A service-level property called `build` would look like: -```yaml -service: - build: ... -``` - -Note that in your Compose file, you will need a top-level property called `services` to contain all of your services. For example: -```yaml -services: - service: - build: ... -``` -::: - -### `build` -(Required, unless `image` is defined) - -The build configuration. - -```yaml -build: - context: . - dockerfile: ./Dockerfile -``` - -### `command` -(Optional) - -The command which will be run to start your service. If left out, the command from the docker image will be used. - -```yaml -command: nginx -g 'daemon off;' -``` - -### `deploy` -(Optional) - -The runtime constraints or requirements for how your services will be deployed and managed across different environments (e.g. memory reservations, replicas, number of CPUs, etc.). - -```yaml -deploy: - replicas: 1 - reservations: - cpus: '0.5' - memory: 256M -``` - -### `depends_on` -(Unsupported) - -The services that need to be started before this service can run. This feature is currently unsupported by Defang, but can be useful in local developments such as Docker. - -```yaml -# depends_on: -# - db -``` - -### `environment` -(Optional) - -The environment variables to set. For sensitive environment variables, you can set them with a blank or `null` value. -```yaml -environment: - DATABASE_USER: someuser - DATABASE_PASSWORD: # leave blank/null to set config -``` - -Alternatively, you can use *list notation* to write your Compose files: -```yaml -environment: - - DATABASE_USER=someuser - - DATABASE_PASSWORD -``` - -:::info -After you set sensitive environment variables as blank or `null` values in the `compose.yaml` file, you can securely set their actual value in the Defang CLI. See our [Configuration page](/docs/concepts/configuration) for more. -::: - -### `healthcheck` -(Optional, but required for healthchecks on services with a published port) - -The healthcheck endpoints for the container. Note that `curl` is commonly used for containers with a `slim`-based image, and `wget` is used for containers with an `alpine`-based image. - -```yaml -healthcheck: - test: ["CMD", "curl", "-f", "http://localhost:8080/"] -``` - -or - -```yaml -healthcheck: - test: ["CMD", "wget", "--spider", "http://localhost:8080/"] -``` - -### `image` -(Required, unless `build` is defined) - -The image to run. - -```yaml -image: nginx:latest -``` - -### `networks` -(Optional) - -The network configuration. Can be `public`, where Defang will assign a public IP address, or `private`, in which Defang will not. To avoid warnings, add this to the `networks` top-level property as well. - -```yaml -networks: - public: -``` - -You can also assign an alias for a network by using `aliases`, as seen below: -```yaml -networks: - public: - aliases: - - app -``` - -### `ports` -(Optional, but required if you want to access the service from outside the container) - -The ports to expose. Mode should be specified as `ingress`. - -```yaml -ports: - - mode: ingress - target: 80 - published: 8080 -``` - -:::info -Defang ignores `published` ports in production. As such, it is common to make `target` and `published` ports the same when using Defang. However, it can be useful to include a `published` port for local development, such as Docker. -::: - -### `restart` -(Optional, but highly recommended) - -The restart mode for a container. Defaults to `unless-stopped` unless otherwise specified. - -```yaml -restart: unless-stopped -``` - -### `volumes` -(Unsupported) - -The volume mounts for a container, specific to a service. This feature is not currently supported by Defang. - -```yaml -# volumes: -# - "./backend:/app" -``` diff --git a/docs/concepts/compose.md b/docs/concepts/compose.md index 3ae03f43e..6452a9dd4 100644 --- a/docs/concepts/compose.md +++ b/docs/concepts/compose.md @@ -6,39 +6,241 @@ sidebar_position: 150 # Compose -You might be familiar with `docker-compose.yml` files, now known as the [Compose specification](https://docs.docker.com/compose/compose-file/) and `compose.yaml` files. It's a simple way to define and run multi-container Docker applications. Defang allows you to use `compose.yaml` files to deploy your application to the cloud. +Defang allows you to use `compose.yaml` files to deploy your application to the cloud. +The `compose.yaml` file is a simple way to define and run multi-container applications. +This file format may look familiar to you if you've come across `docker-compose.yml` files, as both are based on the [Compose specification](https://docs.docker.com/compose/compose-file/). -## How it works +## How It Works -You can define your [services](./services.md) using a `compose.yaml` file in the root of your project, or use the [`defang generate` command](../tutorials/generate-new-code-using-ai.mdx) to generate one (along with other resources). This file is used to define your application's services and how they run. You can edit this file to add more services or change the configuration of existing services. +You can create a `compose.yaml` file in the root of your project, or use the [`defang generate`](../tutorials/generate-new-code-using-ai.mdx) command to create one for you (along with other resources). This file is used to define your application's [services](./services.md) and how they run. You can edit this file to add more services or change the configuration of existing services. When you run `defang compose up`, Defang will read your `compose.yaml` file and [deploy](./deployments.md) the services named in that file to the cloud. ## Service Name Resolution -One thing to keep in mind is that, at the time of this writing, Defang identifies services by the [user/account name](./accounts.md) and the service name (as defined in the `compose.yaml` file). This means that if you have multiple Defang projects with the same service name, they will conflict with each other. We plan to provide a more robust system for managing service names and protecting against conflicts in the future. +Defang identifies services by the [account username](./accounts.md) and the service name (as defined in the `compose.yaml` file). This means that if you have multiple Defang projects with the same service name, they will conflict with each other. We plan to provide a more robust system for managing service names in the future. -## Configuration +## Example of a Compose File +Here is a basic `compose.yaml` file that contains all the required properties for deployment in Defang. -If you have a service that depends on a secret like an api key, you can set that [secret](./configuration.md) using the CLI: +```yaml +services: + service-example: + image: nginx:latest # use one of: an image (shown on this line) or a build (shown below) + # build: + # context: . + # dockerfile: Dockerfile + ports: + - mode: ingress # specify ports to expose + target: 8080 + published: 80 + +``` + +## Compose Top-level Properties +Here are a list of top-level properties of the [Compose specification](https://docs.docker.com/compose/compose-file/) that Defang supports when writing a `compose.yaml` file. + +### `networks` +(Optional) + +The networks defined in your application. This is commonly added together with a [service-level `networks`](#networks-1) property. +```yaml +networks: + public: ``` -defang config set --name MY_API_KEY + +### `services` +(Required) + +The services defined in your application. + +```yaml +services: + service: + # add service-level properties here ``` -and then connect it to the service by specifying it in the `compose.yaml`: +### `version` +(Deprecated) + +The version of the Compose file format being used. This feature is no longer supported and will be ignored by Defang. + +```yaml +# version: '3' +``` + +### `volumes` +(Unsupported) + +The volume mounts for a container, reusable across services. This feature is not currently supported by Defang. + +```yaml +# volumes: +# db-data: +``` + +:::warning +Defang does not support the `secrets` top-level property. Please read our [Configuration](/docs/concepts/configuration) page instead. +::: + +## Compose Service-level Properties +Here are a list of service-level properties of the [Compose specification](https://docs.docker.com/compose/compose-file/) that Defang supports when writing a `compose.yaml` file. + +:::tip +Service-level means inside your `service`. A service-level property called `build` would look like: +```yaml +service: + build: ... +``` +Note that in your Compose file, you will need a top-level property called `services` to contain all of your services. For example: ```yaml services: - my-service: - secrets: - - MY_API_KEY + service: + build: ... +``` +::: + +### `build` +(Required, unless `image` is defined) + +The build configuration. + +```yaml +build: + context: . + dockerfile: ./Dockerfile +``` + +### `command` +(Optional) + +The command which will be run to start your service. If left out, the command from the Docker image will be used. + +```yaml +command: nginx -g 'daemon off;' +``` + +### `deploy` +(Optional) + +The runtime constraints or requirements for how your services will be deployed and managed across different environments (e.g. memory reservations, replicas, number of CPUs, etc.). + +```yaml +deploy: + replicas: 1 + reservations: + cpus: '0.5' + memory: 256M +``` + +### `depends_on` +(Unsupported) + +The services that need to be started before this service can run. This feature is currently unsupported by Defang, but can be useful in local developments such as Docker. -secrets: - MY_API_KEY: - external: true +```yaml +# depends_on: +# - db +``` + +### `environment` +(Optional) + +The environment variables to set. For sensitive environment variables, you can set them with a blank or `null` value. +```yaml +environment: + DATABASE_USER: someuser + DATABASE_PASSWORD: # leave blank/null to set config +``` + +The above uses *map notation*. Defang also supports using *list notation*: +```yaml +environment: + - DATABASE_USER=someuser + - DATABASE_PASSWORD +``` + +:::info +After you set sensitive environment variables as blank or `null` values in the `compose.yaml` file, you can securely set their actual value in the Defang CLI. See our [Configuration page](/docs/concepts/configuration) for more. +::: + +### `healthcheck` +(Optional, but required for healthchecks on services with a published port) + +The healthcheck endpoints for the container. Note that `curl` is commonly used for containers with a `slim`-based image, and `wget` is used for containers with an `alpine`-based image. + +```yaml +healthcheck: + test: ["CMD", "curl", "-f", "http://localhost:8080/"] +``` + +or + +```yaml +healthcheck: + test: ["CMD", "wget", "--spider", "http://localhost:8080/"] +``` + +### `image` +(Required, unless `build` is defined) + +The image to run. + +```yaml +image: nginx:latest +``` + +### `networks` +(Optional) + +The network configuration. Can be `public`, where Defang will assign a public IP address, or `private`, in which Defang will not. To avoid warnings, add this to the [top-level `networks`](#networks) property as well. + +```yaml +networks: + public: ``` -:::info Configuration & Secrets -Read more about configuration in the [configuration page](./configuration.md). +You can also assign an alias for a network by using `aliases`, as seen below: +```yaml +networks: + public: + aliases: + - app +``` + +### `ports` +(Optional, but required if you want to access the service from outside the container) + +The ports to expose. Mode should be specified as `ingress`. + +```yaml +ports: + - mode: ingress + target: 80 + published: 8080 +``` + +:::info +Defang ignores `published` ports in production. As such, it is common to make `target` and `published` ports the same when using Defang. However, it can be useful to include a `published` port for local development, such as Docker. ::: + +### `restart` +(Optional, but highly recommended) + +The restart mode for a container. Defaults to `unless-stopped` unless otherwise specified. + +```yaml +restart: unless-stopped +``` + +### `volumes` +(Unsupported) + +The volume mounts for a container, specific to a service. This feature is not currently supported by Defang. + +```yaml +# volumes: +# - "./backend:/app" +``` From 42201811467f5b586e5623de552cc1aa0c2e095b Mon Sep 17 00:00:00 2001 From: commit111 Date: Wed, 8 Jan 2025 09:22:05 -0800 Subject: [PATCH 16/28] edit description --- docs/concepts/compose.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/concepts/compose.md b/docs/concepts/compose.md index 6452a9dd4..3d6bd9d0f 100644 --- a/docs/concepts/compose.md +++ b/docs/concepts/compose.md @@ -213,7 +213,7 @@ networks: ### `ports` (Optional, but required if you want to access the service from outside the container) -The ports to expose. Mode should be specified as `ingress`. +The ports to expose. The default port mode is `ingress`. ```yaml ports: From 57f642a26369dc0153a2e51ae007981ae7284f59 Mon Sep 17 00:00:00 2001 From: commit111 Date: Wed, 8 Jan 2025 12:57:49 -0800 Subject: [PATCH 17/28] move service name resolution --- docs/concepts/compose.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/docs/concepts/compose.md b/docs/concepts/compose.md index 3d6bd9d0f..c93cdc6a9 100644 --- a/docs/concepts/compose.md +++ b/docs/concepts/compose.md @@ -16,10 +16,6 @@ You can create a `compose.yaml` file in the root of your project, or use the [`d When you run `defang compose up`, Defang will read your `compose.yaml` file and [deploy](./deployments.md) the services named in that file to the cloud. -## Service Name Resolution - -Defang identifies services by the [account username](./accounts.md) and the service name (as defined in the `compose.yaml` file). This means that if you have multiple Defang projects with the same service name, they will conflict with each other. We plan to provide a more robust system for managing service names in the future. - ## Example of a Compose File Here is a basic `compose.yaml` file that contains all the required properties for deployment in Defang. @@ -61,6 +57,10 @@ services: # add service-level properties here ``` +:::info Service Name Resolution +Defang identifies services by the [account username](./accounts.md) and the service name (as defined in the `compose.yaml` file). This means that if you have multiple Defang projects with the same service name, they will conflict with each other. We recommend using a different name for each service you define. +::: + ### `version` (Deprecated) @@ -81,7 +81,7 @@ The volume mounts for a container, reusable across services. This feature is not ``` :::warning -Defang does not support the `secrets` top-level property. Please read our [Configuration](/docs/concepts/configuration) page instead. +Defang does not support the `secrets` top-level property. Please read our [Configuration](/docs/concepts/configuration) page for more. ::: ## Compose Service-level Properties From 2faa8d97ccba9acc375f1a90a05d950619e01417 Mon Sep 17 00:00:00 2001 From: commit111 Date: Wed, 8 Jan 2025 13:31:27 -0800 Subject: [PATCH 18/28] add service name resolution from compose to services page --- docs/concepts/compose.md | 4 ++-- docs/concepts/services.md | 12 ++++++++---- 2 files changed, 10 insertions(+), 6 deletions(-) diff --git a/docs/concepts/compose.md b/docs/concepts/compose.md index c93cdc6a9..c71c0b420 100644 --- a/docs/concepts/compose.md +++ b/docs/concepts/compose.md @@ -57,8 +57,8 @@ services: # add service-level properties here ``` -:::info Service Name Resolution -Defang identifies services by the [account username](./accounts.md) and the service name (as defined in the `compose.yaml` file). This means that if you have multiple Defang projects with the same service name, they will conflict with each other. We recommend using a different name for each service you define. +:::info +Defang identifies services by the [account username](./accounts.md) and the service name (as defined in the `compose.yaml` file). This means that if you have multiple Defang projects with the same service name, they will conflict with each other. See our [Services](/docs/concepts/services) page for more. ::: ### `version` diff --git a/docs/concepts/services.md b/docs/concepts/services.md index 0758dc29d..4487e7223 100644 --- a/docs/concepts/services.md +++ b/docs/concepts/services.md @@ -10,14 +10,18 @@ Defang allows you deploy services defined as containers. You can define your ser `-` -You can learn more about accounts and usernames in the [accounts page](./accounts.md). +### Service Name Resolution +As shown above, Defang identifies services by the [account username](./accounts.md) and the service name. -:::tip Service Names +:::tip Service names are defined in your Compose file or your Pulumi program. ::: -You can learn more about about how to define [services with Compose files here](./compose.md) and [services with Pulumi here](./pulumi.md). You can learn more about how services are deployed in the [deployment page](./deployments.md). +This means that if you have multiple Defang projects with the same service name, they will conflict with each other. To avoid naming conflicts, we recommend using a different name for each service you define. + +### Service Deployment +Defang manages the deployment process for services. You can learn more about how services are deployed in the [Deployment page](./deployments.md). :::info -While this is the current state of the Defang model, we plan to add support for other types of services in the future, including serverless functions. +We plan to add support for other types of services in the future, including serverless functions. ::: From 793e61766f911e73f8f3cba459368a3cd37de6ed Mon Sep 17 00:00:00 2001 From: Linda Lee Date: Wed, 8 Jan 2025 15:52:12 -0800 Subject: [PATCH 19/28] Apply suggestions from code review Co-authored-by: Jordan Stephens --- docs/concepts/compose.md | 28 +++++++++++++++++++++------- 1 file changed, 21 insertions(+), 7 deletions(-) diff --git a/docs/concepts/compose.md b/docs/concepts/compose.md index c71c0b420..710f80d2b 100644 --- a/docs/concepts/compose.md +++ b/docs/concepts/compose.md @@ -64,7 +64,7 @@ Defang identifies services by the [account username](./accounts.md) and the serv ### `version` (Deprecated) -The version of the Compose file format being used. This feature is no longer supported and will be ignored by Defang. +The version of the Compose file format being used. This property is now obsolete, and will be ignored by Defang. ```yaml # version: '3' @@ -105,7 +105,7 @@ services: ### `build` (Required, unless `image` is defined) -The build configuration. +The [build configuration](https://github.com/compose-spec/compose-spec/blob/main/build.md). This property describes how to create an OCI container for this service. ```yaml build: @@ -125,7 +125,7 @@ command: nginx -g 'daemon off;' ### `deploy` (Optional) -The runtime constraints or requirements for how your services will be deployed and managed across different environments (e.g. memory reservations, replicas, number of CPUs, etc.). +The [Deploy Specification](https://github.com/compose-spec/compose-spec/blob/main/deploy.md) describes the runtime constraints and requirements for how your services will be deployed and managed across different environments (e.g. memory reservations, replicas, number of CPUs, etc.). ```yaml deploy: @@ -138,7 +138,7 @@ deploy: ### `depends_on` (Unsupported) -The services that need to be started before this service can run. This feature is currently unsupported by Defang, but can be useful in local developments such as Docker. +This property describes startup dependencies between services. This feature is currently unsupported by Defang, but can be useful in local developments such as Docker. ```yaml # depends_on: @@ -148,7 +148,7 @@ The services that need to be started before this service can run. This feature i ### `environment` (Optional) -The environment variables to set. For sensitive environment variables, you can set them with a blank or `null` value. +The environment variables to set. ```yaml environment: DATABASE_USER: someuser @@ -169,11 +169,20 @@ After you set sensitive environment variables as blank or `null` values in the ` ### `healthcheck` (Optional, but required for healthchecks on services with a published port) -The healthcheck endpoints for the container. Note that `curl` is commonly used for containers with a `slim`-based image, and `wget` is used for containers with an `alpine`-based image. +[This property](https://github.com/compose-spec/compose-spec/blob/main/05-services.md#healthcheck) describes a check that will be run to determine whether or not a service's containers are "healthy". It works in the same way, and has the same default values, as the [HEALTHCHECK Dockerfile instruction](https://docs.docker.com/engine/reference/builder/#healthcheck) set by the service's Docker image. Your Compose file can override the values set in the Dockerfile. + +When using Defang, your compose file must have a healthcheck if you want to expose a port—even if your dockerfile already contains one + +:::note +`curl` is commonly used for containers with a `slim`-based image, and `wget` is used for containers with an `alpine`-based image. +::: ```yaml healthcheck: test: ["CMD", "curl", "-f", "http://localhost:8080/"] + interval: 30s + timeout: 90s + retries: 3 ``` or @@ -181,12 +190,15 @@ or ```yaml healthcheck: test: ["CMD", "wget", "--spider", "http://localhost:8080/"] + interval: 30s + timeout: 90s + retries: 3 ``` ### `image` (Required, unless `build` is defined) -The image to run. +[This property](https://github.com/compose-spec/compose-spec/blob/main/05-services.md#image) describes the image from which your container should start. ```yaml image: nginx:latest @@ -210,6 +222,8 @@ networks: - app ``` +See our [Networking](/docs/concepts/networking) page for more. + ### `ports` (Optional, but required if you want to access the service from outside the container) From f37f4d0b4692340d34bdd040506f65f67f95f8d6 Mon Sep 17 00:00:00 2001 From: Linda Lee Date: Wed, 8 Jan 2025 15:57:46 -0800 Subject: [PATCH 20/28] Update docs/concepts/compose.md Co-authored-by: Jordan Stephens --- docs/concepts/compose.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/docs/concepts/compose.md b/docs/concepts/compose.md index 710f80d2b..f2561f1f9 100644 --- a/docs/concepts/compose.md +++ b/docs/concepts/compose.md @@ -46,6 +46,8 @@ networks: public: ``` +See our [Networking](/docs/concepts/networking) page for more. + ### `services` (Required) From dbda400fa999d89f33d349192c0c8ff3d8960f74 Mon Sep 17 00:00:00 2001 From: commit111 Date: Wed, 8 Jan 2025 15:59:09 -0800 Subject: [PATCH 21/28] fix grammar --- docs/concepts/compose.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/concepts/compose.md b/docs/concepts/compose.md index 710f80d2b..7871c20ba 100644 --- a/docs/concepts/compose.md +++ b/docs/concepts/compose.md @@ -171,7 +171,7 @@ After you set sensitive environment variables as blank or `null` values in the ` [This property](https://github.com/compose-spec/compose-spec/blob/main/05-services.md#healthcheck) describes a check that will be run to determine whether or not a service's containers are "healthy". It works in the same way, and has the same default values, as the [HEALTHCHECK Dockerfile instruction](https://docs.docker.com/engine/reference/builder/#healthcheck) set by the service's Docker image. Your Compose file can override the values set in the Dockerfile. -When using Defang, your compose file must have a healthcheck if you want to expose a port—even if your dockerfile already contains one +When using Defang, your compose file must have a healthcheck if you want to expose a port—even if your Dockerfile already contains one. :::note `curl` is commonly used for containers with a `slim`-based image, and `wget` is used for containers with an `alpine`-based image. From 6dd6d0182b67e101424c08007f9ad3d4d07d47ea Mon Sep 17 00:00:00 2001 From: commit111 Date: Tue, 14 Jan 2025 11:51:54 -0800 Subject: [PATCH 22/28] improve config section --- docs/concepts/compose.md | 15 ++++++--------- 1 file changed, 6 insertions(+), 9 deletions(-) diff --git a/docs/concepts/compose.md b/docs/concepts/compose.md index c93aaa707..7e99d48eb 100644 --- a/docs/concepts/compose.md +++ b/docs/concepts/compose.md @@ -154,18 +154,15 @@ The environment variables to set. ```yaml environment: DATABASE_USER: someuser - DATABASE_PASSWORD: # leave blank/null to set config ``` - -The above uses *map notation*. Defang also supports using *list notation*: +:::info +For sensitive environment variables (or secret values), you should list the variable's name with a blank or `null` value, and then securely set their actual value with `defang config` in the CLI. See our [Configuration page](/docs/concepts/configuration) for more. + + For example: ```yaml -environment: - - DATABASE_USER=someuser - - DATABASE_PASSWORD + - DATABASE_USER=someuser # env var loaded with this literal value + - DATABASE_PASSWORD # env var loaded using defang config ``` - -:::info -After you set sensitive environment variables as blank or `null` values in the `compose.yaml` file, you can securely set their actual value in the Defang CLI. See our [Configuration page](/docs/concepts/configuration) for more. ::: ### `healthcheck` From 0b011837813aab9d69eafe805457873e3ec74df6 Mon Sep 17 00:00:00 2001 From: Linda Lee Date: Tue, 14 Jan 2025 12:00:09 -0800 Subject: [PATCH 23/28] Apply suggestions from code review MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Lio李歐 --- docs/concepts/compose.md | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) diff --git a/docs/concepts/compose.md b/docs/concepts/compose.md index 7e99d48eb..1b2c11e83 100644 --- a/docs/concepts/compose.md +++ b/docs/concepts/compose.md @@ -12,7 +12,7 @@ This file format may look familiar to you if you've come across `docker-compose. ## How It Works -You can create a `compose.yaml` file in the root of your project, or use the [`defang generate`](../tutorials/generate-new-code-using-ai.mdx) command to create one for you (along with other resources). This file is used to define your application's [services](./services.md) and how they run. You can edit this file to add more services or change the configuration of existing services. +You can create a `compose.yaml` file in the root of your project, or use the [`defang generate`](../tutorials/generate-new-code-using-ai.mdx) command to create one for you (along with other resources). This file is used to define your application's [services](./services.md) and how they run. You can edit this file to add more services or change the configuration of services. When you run `defang compose up`, Defang will read your `compose.yaml` file and [deploy](./deployments.md) the services named in that file to the cloud. @@ -22,14 +22,14 @@ Here is a basic `compose.yaml` file that contains all the required properties fo ```yaml services: service-example: - image: nginx:latest # use one of: an image (shown on this line) or a build (shown below) + image: nginx:latest # use one of: image (shown on this line) or build (shown below) # build: # context: . # dockerfile: Dockerfile ports: - mode: ingress # specify ports to expose target: 8080 - published: 80 + published: 8080 # this is useful for running locally ``` @@ -73,7 +73,7 @@ The version of the Compose file format being used. This property is now obsolete ``` ### `volumes` -(Unsupported) +(Not yet supported) The volume mounts for a container, reusable across services. This feature is not currently supported by Defang. @@ -138,7 +138,7 @@ deploy: ``` ### `depends_on` -(Unsupported) +(Not yet supported) This property describes startup dependencies between services. This feature is currently unsupported by Defang, but can be useful in local developments such as Docker. @@ -170,10 +170,10 @@ For sensitive environment variables (or secret values), you should list the vari [This property](https://github.com/compose-spec/compose-spec/blob/main/05-services.md#healthcheck) describes a check that will be run to determine whether or not a service's containers are "healthy". It works in the same way, and has the same default values, as the [HEALTHCHECK Dockerfile instruction](https://docs.docker.com/engine/reference/builder/#healthcheck) set by the service's Docker image. Your Compose file can override the values set in the Dockerfile. -When using Defang, your compose file must have a healthcheck if you want to expose a port—even if your Dockerfile already contains one. +When using Defang, your Compose file must have a healthcheck if you want to expose an `ingress` port—even if your Dockerfile already contains one. :::note -`curl` is commonly used for containers with a `slim`-based image, and `wget` is used for containers with an `alpine`-based image. +`curl` is commonly used for containers with an Ubuntu-based image, and `wget` is used for containers with an `alpine`-based image. ::: ```yaml @@ -232,7 +232,7 @@ The ports to expose. The default port mode is `ingress`. ports: - mode: ingress target: 80 - published: 8080 + published: 80 ``` :::info From d7e62892dd2b4931e04ee42cece244f63c6d5f2f Mon Sep 17 00:00:00 2001 From: Linda Lee Date: Wed, 15 Jan 2025 14:06:58 -0800 Subject: [PATCH 24/28] Apply suggestions from code review MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Jordan Stephens Co-authored-by: Lio李歐 --- docs/concepts/compose.md | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/docs/concepts/compose.md b/docs/concepts/compose.md index 1b2c11e83..e7a2a993b 100644 --- a/docs/concepts/compose.md +++ b/docs/concepts/compose.md @@ -8,7 +8,9 @@ sidebar_position: 150 Defang allows you to use `compose.yaml` files to deploy your application to the cloud. The `compose.yaml` file is a simple way to define and run multi-container applications. -This file format may look familiar to you if you've come across `docker-compose.yml` files, as both are based on the [Compose specification](https://docs.docker.com/compose/compose-file/). +This file format may look familiar to you if you've used [Docker](https://docker.com). + +The [Compose Specification](https://github.com/compose-spec/compose-spec/blob/main/spec.md#compose-file) lets you define a platform-agnostic application designed as a set of containers which are configured to run together with shared resources. These applications may be destined for any [OCI](https://opencontainers.org/) Container Runtime. Defang does the heavy lifting to deploy to your favourite cloud platform using this file. ## How It Works @@ -249,7 +251,7 @@ restart: unless-stopped ``` ### `volumes` -(Unsupported) +(Not yet supported) The volume mounts for a container, specific to a service. This feature is not currently supported by Defang. From 856397b38169ebb04d328c5ea703050565e6b19c Mon Sep 17 00:00:00 2001 From: Linda Lee Date: Wed, 15 Jan 2025 14:38:52 -0800 Subject: [PATCH 25/28] Update docs/concepts/compose.md MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Lio李歐 --- docs/concepts/compose.md | 9 --------- 1 file changed, 9 deletions(-) diff --git a/docs/concepts/compose.md b/docs/concepts/compose.md index e7a2a993b..46af91011 100644 --- a/docs/concepts/compose.md +++ b/docs/concepts/compose.md @@ -65,15 +65,6 @@ services: Defang identifies services by the [account username](./accounts.md) and the service name (as defined in the `compose.yaml` file). This means that if you have multiple Defang projects with the same service name, they will conflict with each other. See our [Services](/docs/concepts/services) page for more. ::: -### `version` -(Deprecated) - -The version of the Compose file format being used. This property is now obsolete, and will be ignored by Defang. - -```yaml -# version: '3' -``` - ### `volumes` (Not yet supported) From dd9f070cb0a6c1a9fffa0bfe83a30a1a79960284 Mon Sep 17 00:00:00 2001 From: commit111 Date: Wed, 15 Jan 2025 16:07:11 -0800 Subject: [PATCH 26/28] move required properties above, and improve services tip --- docs/concepts/compose.md | 76 ++++++++++++++++++++-------------------- 1 file changed, 38 insertions(+), 38 deletions(-) diff --git a/docs/concepts/compose.md b/docs/concepts/compose.md index 46af91011..a09e17b00 100644 --- a/docs/concepts/compose.md +++ b/docs/concepts/compose.md @@ -38,18 +38,6 @@ services: ## Compose Top-level Properties Here are a list of top-level properties of the [Compose specification](https://docs.docker.com/compose/compose-file/) that Defang supports when writing a `compose.yaml` file. -### `networks` -(Optional) - -The networks defined in your application. This is commonly added together with a [service-level `networks`](#networks-1) property. - -```yaml -networks: - public: -``` - -See our [Networking](/docs/concepts/networking) page for more. - ### `services` (Required) @@ -62,9 +50,21 @@ services: ``` :::info -Defang identifies services by the [account username](./accounts.md) and the service name (as defined in the `compose.yaml` file). This means that if you have multiple Defang projects with the same service name, they will conflict with each other. See our [Services](/docs/concepts/services) page for more. +Defang identifies a service based on your username, project name, and the service name you've defined under the `services` property. See our [Services](/docs/concepts/services) page for more about how Defang resolves service names. ::: +### `networks` +(Optional) + +The networks defined in your application. This is commonly added together with a [service-level `networks`](#networks-1) property. + +```yaml +networks: + public: +``` + +See our [Networking](/docs/concepts/networking) page for more. + ### `volumes` (Not yet supported) @@ -108,6 +108,31 @@ build: dockerfile: ./Dockerfile ``` +### `image` +(Required, unless `build` is defined) + +[This property](https://github.com/compose-spec/compose-spec/blob/main/05-services.md#image) describes the image from which your container should start. + +```yaml +image: nginx:latest +``` + +### `ports` +(Optional, but required if you want to access the service from outside the container) + +The ports to expose. The default port mode is `ingress`. + +```yaml +ports: + - mode: ingress + target: 80 + published: 80 +``` + +:::info +Defang ignores `published` ports in production. As such, it is common to make `target` and `published` ports the same when using Defang. However, it can be useful to include a `published` port for local development, such as Docker. +::: + ### `command` (Optional) @@ -187,15 +212,6 @@ healthcheck: retries: 3 ``` -### `image` -(Required, unless `build` is defined) - -[This property](https://github.com/compose-spec/compose-spec/blob/main/05-services.md#image) describes the image from which your container should start. - -```yaml -image: nginx:latest -``` - ### `networks` (Optional) @@ -216,22 +232,6 @@ networks: See our [Networking](/docs/concepts/networking) page for more. -### `ports` -(Optional, but required if you want to access the service from outside the container) - -The ports to expose. The default port mode is `ingress`. - -```yaml -ports: - - mode: ingress - target: 80 - published: 80 -``` - -:::info -Defang ignores `published` ports in production. As such, it is common to make `target` and `published` ports the same when using Defang. However, it can be useful to include a `published` port for local development, such as Docker. -::: - ### `restart` (Optional, but highly recommended) From b66216a8b50ae8cf6fb09ce7abb514a38b7c94c6 Mon Sep 17 00:00:00 2001 From: commit111 Date: Wed, 15 Jan 2025 16:07:36 -0800 Subject: [PATCH 27/28] improve services page according to compose tip --- docs/concepts/services.md | 29 +++++++++++++++++++++++------ 1 file changed, 23 insertions(+), 6 deletions(-) diff --git a/docs/concepts/services.md b/docs/concepts/services.md index 4487e7223..9eb609040 100644 --- a/docs/concepts/services.md +++ b/docs/concepts/services.md @@ -4,20 +4,37 @@ description: Defang allows you deploy services, defined as containers, to the cl sidebar_position: 200 --- -# Services +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; -Defang allows you deploy services defined as containers. You can define your services using a [Compose file](./compose.md) or a [Pulumi program](./pulumi.md). Services can be exposed to the internet or kept private, and can communicate between themselves using the following conventions for hostnames: +# Services -`-` +Defang allows you deploy services defined as containers. You can define your services using a [Compose file](./compose.md) or a [Pulumi program](./pulumi.md). Services can be exposed to the internet or kept private, and can communicate between themselves using certain conventions for hostnames. ### Service Name Resolution -As shown above, Defang identifies services by the [account username](./accounts.md) and the service name. + +Defang identifies services by using your [account username](/docs/concepts/accounts), [project name](/docs/concepts/projects), and service name. The port is included in the [domain](/docs/concepts/domains) for the service. + :::tip -Service names are defined in your Compose file or your Pulumi program. +Service names are defined in your Compose file or in your Pulumi program. ::: -This means that if you have multiple Defang projects with the same service name, they will conflict with each other. To avoid naming conflicts, we recommend using a different name for each service you define. + + + Domains for services in Playground follow the following pattern: + ``` + ---.prod1a.defang.dev + ``` + + + Domains for services in Defang BYOC follow the following pattern: + ``` + --...defang.app + ``` + + + ### Service Deployment Defang manages the deployment process for services. You can learn more about how services are deployed in the [Deployment page](./deployments.md). From 7e602ce62fc85f4933c58711d7f43b3717a0e3a8 Mon Sep 17 00:00:00 2001 From: commit111 Date: Wed, 15 Jan 2025 16:08:00 -0800 Subject: [PATCH 28/28] fix domain example for services --- docs/concepts/domains.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/concepts/domains.mdx b/docs/concepts/domains.mdx index 45204af08..15fb414ae 100644 --- a/docs/concepts/domains.mdx +++ b/docs/concepts/domains.mdx @@ -30,7 +30,7 @@ https://---.defang.dev If you're using [Defang BYOC](./defang-byoc.md), your domain will be: ``` -https://--..defang.app +https://--...defang.app ```