# Docker
The module provides dynamic configuration of proxied server groups
in both [HTTP](https://en.angie.software//angie/docs/configuration/modules/http/http_upstream.md#u-upstream) and [stream](https://en.angie.software//angie/docs/configuration/modules/stream/stream_upstream.md#s-u-upstream)
contexts based on Docker container labels.
For the functionality to work, a shared memory zone must be configured
in the group (see the `zone` description for [http](https://en.angie.software//angie/docs/configuration/modules/http/http_upstream.md#u-zone) and [stream](https://en.angie.software//angie/docs/configuration/modules/stream/stream_upstream.md#s-u-zone)).
#### NOTE
The module supports working with both Docker and its alternatives,
such as Podman, which implement a compatible API.
The module connects to the Docker daemon via API,
the interaction method with which is specified by the [docker_endpoint](#docker-endpoint) directive.
After obtaining a list of running containers,
Angie analyzes them for the presence of suitable [labels](#docker-labels).
If a container description contains a label with a port,
then the address and port of such a container,
as well as parameters from other labels of this container,
are automatically added to the corresponding `upstream` block
in the Angie configuration.
#### NOTE
The same container can be added to multiple `upstream` groups.
To do this, simply specify multiple sets of labels
with different group names and ports.
This is especially useful
if the container runs several different services on different ports —
each service can be associated with its own group.
The module then subscribes to container lifecycle events
and begins updating the proxied server configuration without reloading Angie:
- when starting a container with suitable labels,
its internal IP address is added to the specified group;
- when stopping or removing a container,
it is automatically removed from the group;
- when pausing a container with the **docker pause** command,
the server is marked as `down`,
and with **docker unpause** — as `up`.
## Configuration Example
The module's directives are always located in the `http` context,
but proxied server groups can be defined
in both the `http` context and the `stream` context.
Configuration example for `http`:
```nginx
http {
# Examples of connection options:
# docker_endpoint http://127.0.0.1:2375;
# docker_endpoint https://127.0.0.1:2376;
docker_endpoint unix:/var/run/docker.sock;
# maximum Docker response buffer size (optional)
# docker_max_object_size 128k;
upstream u {
zone z 1m; # shared memory zone is required
}
server {
listen 80;
server_name example.com;
location / {
proxy_pass http://u;
}
}
}
```
Similarly in stream context:
```nginx
http {
# Examples of connection options:
# docker_endpoint http://127.0.0.1:2375;
# docker_endpoint https://127.0.0.1:2376;
docker_endpoint unix:/var/run/docker.sock;
# maximum Docker response buffer size (optional)
# docker_max_object_size 128k;
}
stream {
upstream u {
zone z 1m;
}
server {
listen 12345;
proxy_pass u;
}
}
```
Upon receiving an event for a container,
Angie looks for labels of the form
`angie.http.upstreams..port=` (for HTTP context)
or `angie.stream.upstreams..port=` (for stream context).
When a label is present, the container's address in the specified Docker network
(or the first available one if the `angie.network` label is not specified)
is added to the corresponding proxied server group.
If a container stops or is removed, the server is removed from the group;
if a container is paused, the server is marked as `down`.
Fragment of a `docker-compose.yml` file with labels that Angie recognizes:
```yaml
services:
myapp:
image: myapp:latest
labels:
- "angie.http.upstreams.u.port=8080"
- "angie.network=my_bridge"
- "angie.http.upstreams.u.weight=2"
- "angie.http.upstreams.u.max_conns=50"
- "angie.http.upstreams.u.max_fails=3"
- "angie.http.upstreams.u.fail_timeout=10s"
- "angie.http.upstreams.u.backup=true"
```
## Labels
Labels specify server parameters in the proxied server group
similar to the arguments of the `server` directive:
| Label | Purpose |
|------------------------------------------------------------------|-----------------------------------------------------------------------------------------------------------|
| `angie.(http|stream).upstreams..port=` *(required)* | Container port that Angie will connect to; the container itself is added to the group named ``. |
| `angie.network=` | Name of the Docker network from which to take the container's IP address. |
| `angie.(http|stream).upstreams..weight=` | Value of the `weight` parameter. |
| `angie.(http|stream).upstreams..max_conns=` | Maximum number of simultaneous connections (`max_conns`). |
| `angie.(http|stream).upstreams..max_fails=` | Threshold for failed attempts (`max_fails`). |
| `angie.(http|stream).upstreams..fail_timeout=` | Interval for counting failed attempts (`fail_timeout`). |
| `angie.(http|stream).upstreams..backup=true|false` | Marks the server as `backup`. |
| `angie.(http|stream).upstreams..sid=` | Sets a custom server identifier (`sid`) for the proxied server. |
| `angie.(http|stream).upstreams..slow_start=