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
Copy file name to clipboardExpand all lines: README.md
+30-4Lines changed: 30 additions & 4 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -85,7 +85,7 @@ Control the default behavior of `nginx-proxy`:
85
85
|`NGINX_WORKER_CONNECTIONS`|`65535`| Max connections per worker. |
86
86
|`CERT_RENEW_THRESHOLD_DAYS`|`30`| By default certificates are renewed when they have <=30 days remaining. |
87
87
|`ENABLE_IPV6`|`false`| Enable IPv6 support on nginx. |
88
-
|`DOCKER_SWARM`|`ignore`|Treats every container like local by defeault. Set `enable` for Swarm support, `strict` for Swarm-only or`exclude` to not include swarm containers |
88
+
|`DOCKER_SWARM`|`ignore`|Controls Docker Swarm discovery. Supported values are `ignore`, `exclude`, `enable`, and `strict`; see [Docker Swarm Support](#docker-swarm-support-preview).|
89
89
|`SWARM_DOCKER_HOST`| - | URL of the Swarm manager socket (e.g., `tcp://manager:2375`). |
90
90
|`CERTAPI_URL`| - | External Certificate API URL. |
91
91
|`CERTAPI_BATCH_DOMAINS`|`true`| When using `CERTAPI_URL`, request safe domain batching (`batch_domains=true`) to avoid recursive domain-order errors. |
**Note** Be aware that if domain as target, nginx will crash if DNS resolution fails.
140
140
141
141
## Docker Swarm Support [Preview]
142
-
Enable swarm mode by setting `DOCKER_SWARM` to `enable` (local & swarm) or `strict` (swarm only).
143
-
If current node is not manager, set `SWARM_DOCKER_HOST=tcp://manager:2375`.
144
142
145
-
**Warning** : Automatic exposed port detection will not work when swarm support is enabled. You must explicitly set port on the `VIRTUAL_HOST` or set `VIRTUAL_PORT` on the container.
143
+
**Warning** : Automatic exposed port detection will not work when swarm support is enabled. You must explicitly set port on the `VIRTUAL_HOST`.
144
+
145
+
146
+
Docker Swarm discovery is controlled by the `DOCKER_SWARM` environment variable on the `nginx-proxy` container.
147
+
148
+
|`DOCKER_SWARM` value | Local containers | Swarm services | Use case |
149
+
| :--- | :--- | :--- | :--- |
150
+
|`ignore`| Included | Not discovered | Default Docker-only behavior. Swarm task containers are treated like standalone containers if they are visible on the local Docker socket. |
151
+
|`exclude`| Included | Not discovered | Docker-only discovery while explicitly ignoring containers that belong to Swarm services. |
152
+
|`enable`| Included | Included | Mixed mode. Use this when `nginx-proxy` should route both standalone containers and Swarm services. |
153
+
|`strict`| Excluded | Included | Swarm-only mode. Use this when `nginx-proxy` should route only Swarm services. |
154
+
155
+
`ignore` is the default and does not require the Docker node to be in Swarm mode. In this mode, `nginx-proxy` only reads the normal Docker container API. If a Swarm task container is visible on the local Docker socket, it can be registered as if it were a regular container.
156
+
157
+
`exclude` still uses only the local Docker container API, but skips containers that have Swarm service labels. This is useful when the same Docker host runs standalone containers and Swarm services, but this proxy instance should only manage standalone containers.
158
+
159
+
`enable` reads both local containers and Swarm services. Standalone containers are discovered from the local Docker socket. Swarm services are discovered from the Swarm manager API, and task containers are skipped so each service is registered once.
160
+
161
+
`strict` reads only Swarm services. Local standalone containers are ignored, and Swarm task containers are also ignored. This is the mode to use when this proxy instance is dedicated to Swarm routing.
162
+
163
+
For `enable` and `strict`, the Swarm API client must be connected to a manager node because Docker only allows managers to list services. If `nginx-proxy` is running on a worker node, set `SWARM_DOCKER_HOST` to a reachable manager Docker API endpoint:
164
+
165
+
```bash
166
+
-e DOCKER_SWARM=enable \
167
+
-e SWARM_DOCKER_HOST=tcp://manager:2375
168
+
```
169
+
170
+
If `SWARM_DOCKER_HOST` is not set, the local Docker socket is used for both local containers and Swarm services. When `SWARM_DOCKER_HOST` is set, `nginx-proxy` uses the local Docker socket for standalone containers and the remote manager socket for Swarm services. If the local Docker socket cannot be reached but `SWARM_DOCKER_HOST` is set, `nginx-proxy` switches to `strict` mode and uses only the remote Swarm manager.
0 commit comments