You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
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.
9
+
Defang allows you to use `compose.yaml` files to deploy your application to the cloud.
10
+
The `compose.yaml` file is a simple way to define and run multi-container applications.
11
+
This file format may look familiar to you if you've used [Docker](https://docker.com).
10
12
11
-
## How it works
13
+
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.
12
14
13
-
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.
15
+
## How It Works
16
+
17
+
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.
14
18
15
19
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.
16
20
17
-
## Service Name Resolution
21
+
## Example of a Compose File
22
+
Here is a basic `compose.yaml` file that contains all the required properties for deployment in Defang.
23
+
24
+
```yaml
25
+
services:
26
+
service-example:
27
+
image: nginx:latest # use one of: image (shown on this line) or build (shown below)
28
+
# build:
29
+
# context: .
30
+
# dockerfile: Dockerfile
31
+
ports:
32
+
- mode: ingress # specify ports to expose
33
+
target: 8080
34
+
published: 8080# this is useful for running locally
35
+
36
+
```
18
37
19
-
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.
38
+
## Compose Top-level Properties
39
+
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.
20
40
21
-
## Configuration
41
+
### `services`
42
+
(Required)
22
43
23
-
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:
44
+
The services defined in your application.
24
45
46
+
```yaml
47
+
services:
48
+
service:
49
+
# add service-level properties here
25
50
```
26
-
defang config set MY_API_KEY
51
+
52
+
:::info
53
+
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.
54
+
:::
55
+
56
+
### `networks`
57
+
(Optional)
58
+
59
+
The networks defined in your application. This is commonly added together with a [service-level `networks`](#networks-1) property.
60
+
61
+
```yaml
62
+
networks:
63
+
public:
27
64
```
28
65
29
-
and then connect it to the service by specifying it in the `compose.yaml`:
66
+
See our [Networking](/docs/concepts/networking) page for more.
67
+
68
+
### `volumes`
69
+
(Not yet supported)
70
+
71
+
The volume mounts for a container, reusable across services. This feature is not currently supported by Defang.
72
+
73
+
```yaml
74
+
# volumes:
75
+
# db-data:
76
+
```
77
+
78
+
:::warning
79
+
Defang does not support the `secrets` top-level property. Please read our [Configuration](/docs/concepts/configuration) page for more.
80
+
:::
81
+
82
+
## Compose Service-level Properties
83
+
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.
84
+
85
+
:::tip
86
+
Service-level means inside your `service`. A service-level property called `build` would look like:
87
+
```yaml
88
+
service:
89
+
build: ...
90
+
```
30
91
92
+
Note that in your Compose file, you will need a top-level property called `services` to contain all of your services. For example:
31
93
```yaml
32
94
services:
33
-
my-service:
34
-
environment:
35
-
- MY_API_KEY
95
+
service:
96
+
build: ...
97
+
```
98
+
:::
99
+
100
+
### `build`
101
+
(Required, unless `image` is defined)
102
+
103
+
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.
104
+
105
+
```yaml
106
+
build:
107
+
context: .
108
+
dockerfile: ./Dockerfile
109
+
```
110
+
111
+
### `image`
112
+
(Required, unless `build` is defined)
113
+
114
+
[This property](https://github.com/compose-spec/compose-spec/blob/main/05-services.md#image) describes the image from which your container should start.
115
+
116
+
```yaml
117
+
image: nginx:latest
118
+
```
119
+
120
+
### `ports`
121
+
(Optional, but required if you want to access the service from outside the container)
122
+
123
+
The ports to expose. The default port mode is `ingress`.
124
+
125
+
```yaml
126
+
ports:
127
+
- mode: ingress
128
+
target: 80
129
+
published: 80
130
+
```
131
+
132
+
:::info
133
+
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.
134
+
:::
135
+
136
+
### `command`
137
+
(Optional)
138
+
139
+
The command which will be run to start your service. If left out, the command from the Docker image will be used.
140
+
141
+
```yaml
142
+
command: nginx -g 'daemon off;'
143
+
```
144
+
145
+
### `deploy`
146
+
(Optional)
147
+
148
+
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.).
149
+
150
+
```yaml
151
+
deploy:
152
+
replicas: 1
153
+
reservations:
154
+
cpus: '0.5'
155
+
memory: 256M
156
+
```
157
+
158
+
### `depends_on`
159
+
(Not yet supported)
160
+
161
+
This property describes startup dependencies between services. This feature is currently unsupported by Defang, but can be useful in local developments such as Docker.
162
+
163
+
```yaml
164
+
# depends_on:
165
+
# - db
36
166
```
37
167
168
+
### `environment`
169
+
(Optional)
170
+
171
+
The environment variables to set.
172
+
```yaml
173
+
environment:
174
+
DATABASE_USER: someuser
175
+
```
38
176
:::info
39
-
Read more about configuration in the [Configuration page](./configuration.md).
177
+
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.
178
+
179
+
For example:
180
+
```yaml
181
+
- DATABASE_USER=someuser # env var loaded with this literal value
182
+
- DATABASE_PASSWORD # env var loaded using defang config
183
+
```
40
184
:::
185
+
186
+
### `healthcheck`
187
+
(Optional, but required for healthchecks on services with a published port)
188
+
189
+
[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.
190
+
191
+
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.
192
+
193
+
:::note
194
+
`curl`is commonly used for containers with an Ubuntu-based image, and `wget` is used for containers with an `alpine`-based image.
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.
219
+
220
+
```yaml
221
+
networks:
222
+
public:
223
+
```
224
+
225
+
You can also assign an alias for a network by using `aliases`, as seen below:
226
+
```yaml
227
+
networks:
228
+
public:
229
+
aliases:
230
+
- app
231
+
```
232
+
233
+
See our [Networking](/docs/concepts/networking) page for more.
234
+
235
+
### `restart`
236
+
(Optional, but highly recommended)
237
+
238
+
The restart mode for a container. Defaults to `unless-stopped` unless otherwise specified.
239
+
240
+
```yaml
241
+
restart: unless-stopped
242
+
```
243
+
244
+
### `volumes`
245
+
(Not yet supported)
246
+
247
+
The volume mounts for a container, specific to a service. This feature is not currently supported by Defang.
Copy file name to clipboardExpand all lines: docs/concepts/configuration.md
+4-3Lines changed: 4 additions & 3 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -19,6 +19,9 @@ defang config set API_KEY
19
19
20
20
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.
21
21
22
+
Either one of list notation or map notation is acceptable for defining your environment variable(s). See below for an example of each.
Copy file name to clipboardExpand all lines: docs/concepts/services.md
+25-4Lines changed: 25 additions & 4 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -4,18 +4,39 @@ description: Defang allows you deploy services, defined as containers, to the cl
4
4
sidebar_position: 200
5
5
---
6
6
7
+
import Tabs from '@theme/Tabs';
8
+
import TabItem from '@theme/TabItem';
9
+
7
10
# Services
8
11
9
-
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:
12
+
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.
13
+
14
+
### Service Name Resolution
10
15
11
-
`<username>-<service-name>`
16
+
Defang identifies services by using your [account username](/docs/concepts/accounts), [project name](/docs/concepts/projects), and servicename. The port is included in the [domain](/docs/concepts/domains) for the service.
12
17
13
-
You can learn more about accounts and usernames in the [Accounts page](./accounts.md).
14
18
15
19
:::tip
16
-
Service names are defined in your Compose file or your Pulumi program.
20
+
Service names are defined in your Compose file or in your Pulumi program.
0 commit comments