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 diff --git a/docs/concepts/compose.md b/docs/concepts/compose.md index 3ae03f43e..12af1d443 100644 --- a/docs/concepts/compose.md +++ b/docs/concepts/compose.md @@ -20,10 +20,10 @@ One thing to keep in mind is that, at the time of this writing, Defang identifie ## Configuration -If you have a service that depends on a secret like an api key, you can set that [secret](./configuration.md) using the CLI: +If you have a service that depends on a [config value](./configuration.md) (such as an API key), you can set it using the CLI: ``` -defang config set --name MY_API_KEY +defang config set MY_API_KEY ``` and then connect it to the service by specifying it in the `compose.yaml`: @@ -31,14 +31,10 @@ and then connect it to the service by specifying it in the `compose.yaml`: ```yaml services: my-service: - secrets: + environment: - MY_API_KEY - -secrets: - MY_API_KEY: - external: true ``` -:::info Configuration & Secrets -Read more about configuration in the [configuration page](./configuration.md). +:::info +Read more about configuration in the [Configuration page](./configuration.md). ::: diff --git a/docs/concepts/configuration.md b/docs/concepts/configuration.md index 6efdd64bf..be57b983f 100644 --- a/docs/concepts/configuration.md +++ b/docs/concepts/configuration.md @@ -8,7 +8,7 @@ sidebar_position: 225 Defang allows you to configure your application using environment variables. You can set environment variables in your [`compose.yaml` file](./compose.md), or in your [Pulumi program](#using-config-with-pulumi). -# Sensitive Config (aka Secrets) +# Sensitive Config Values The Defang CLI allows you to securely store sensitive information such as API keys, passwords, and other credentials. To do so, run: @@ -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: @@ -46,7 +47,7 @@ You can find a sample of how to set sensitive config values [here](https://githu ## Interpolation -Environment variables are set within the *environment* section of a service in a `compose.yaml` file. Any variables declared here will become available within the service container. +Environment variables are set within the `environment` section of a service in a `compose.yaml` file. Any variables declared here will become available within the service container. Variables can be set by assigning a literal value, a reference to a configuration value, or a mix of literal and variable references. Variable references are declared using either **\$\{variable_name\}** or **$variable_name** forms. It is recommended to use the bracketed form. By interpolating over variable references within a string we can construct complex strings. Interpolation may be particularly useful when constructing connection strings to other services. @@ -81,5 +82,6 @@ Here are the different ways sensitive config values are stored depending on the * [DigitalOcean](../providers/digitalocean#secrets) * [GCP](../providers/gcp#secrets) - - +:::info +Please note that while Defang supports setting sensitive config, it does not support the [`secrets`](https://docs.docker.com/reference/compose-file/secrets/) top-level element as seen in the Compose specification. Please see our [Compose](/docs/concepts/compose) page for more details. +::: diff --git a/docs/tutorials/configure-environment-variables.md b/docs/tutorials/configure-environment-variables.md new file mode 100644 index 000000000..46c3d94b3 --- /dev/null +++ b/docs/tutorials/configure-environment-variables.md @@ -0,0 +1,75 @@ +--- +sidebar_position: 400 +title: Configure Environment Variables +description: How to configure sensitive environment variables in Defang. +--- + +# Configure Environment Variables + + +This tutorial will show you how to configure sensitive environment variables in Defang. + +## Pre-requisites +* [A `compose.yaml` file in your project](https://docs.docker.com/compose/gettingstarted/) +* [A Defang Account](/docs/concepts/authentication) +* [The Defang CLI](/docs/getting-started#install-the-defang-cli) + +## Step 1 - Go to your `compose.yaml` file +:::info +If you are using [Pulumi](/docs/concepts/pulumi) instead of Compose files to define your services, please see [Using Config With Pulumi](/docs/concepts/configuration#using-config-with-pulumi) instead. +::: + +In your Compose file, you can define a sensitive config variable for your service by leaving it as a **blank or `null` value**. Defang will recognize it as a sensitive value. + +In the example below, let's define `API_KEY` as an environment variable. + +```yaml +services: + service1: + image: image1:latest + environment: + - API_KEY +``` + +The type of notation shown above is called *list notation*. Alternatively, you can use *map notation*, which is also acceptable: +```yaml +services: + service1: + image: image1:latest + environment: + API_KEY: +``` + +## Step 2 - Set the actual value in the Defang CLI +To store the actual (sensitive) value of the variable, open up a terminal and type the command: +```bash +defang config set API_KEY=actualvalue +``` +Remember to replace `API_KEY` with your variable name and `actualvalue` with your actual value. + +:::tip +You can view all the config variables you are storing in Defang by doing: `defang config ls`. +::: + +### Editing a config value +To edit a value, you can run the command again with an updated value to overwrite the current value: +```bash +defang config set API_KEY=newvalue +``` + +### Removing a config value +To remove a value, run the command: +```bash +defang config rm API_KEY +``` +:::tip +Remember to update your Compose file if you remove an environment variable. +::: + +## Step 3 - Deploy +```bash +defang compose up +``` + +--- +For a deeper discussion on how configuration works in Defang, see our [Configuration docs](/docs/concepts/configuration).