Dokku provides integration with the [Traefik](https://traefik.io/) proxy service by utilizing the Docker label-based integration implemented by Traefik.
```
traefik:report [<app>] [<flag>] # Displays a traefik report for one or more apps
Using the `traefik` plugin integration requires the `docker-compose-plugin` for Docker. See [this document](https://docs.docker.com/compose/install/) from the Docker documentation for more information on the installation process for the `docker-compose-plugin`.
> As using multiple proxy plugins on a single Dokku installation can lead to issues routing requests to apps, doing so should be avoided. As the default proxy implementation is nginx, users are encouraged to stop the nginx service before switching to Traefik.
- Readiness healthchecks defined in `app.json` with a `path` property are automatically transformed into Traefik healthcheck labels.
### Healthchecks
When an app has a readiness healthcheck defined in its `app.json` file with a `path` property, Dokku automatically generates Traefik healthcheck labels. These labels configure Traefik to perform health checks on the container before routing traffic to it.
The following `app.json` healthcheck properties are mapped to Traefik labels:
| `path` | `healthcheck.path` | The HTTP path to check (required) |
| `scheme` | `healthcheck.scheme` | The scheme to use (`http` or `https`) |
| `port` | `healthcheck.port` | The port to check |
| `timeout` | `healthcheck.timeout` | Timeout in seconds (formatted as `Xs`) |
| `wait` | `healthcheck.interval` | Interval between checks in seconds (formatted as `Xs`) |
Example `app.json` configuration:
```json
{
"healthchecks": {
"web": [
{
"name": "web readiness check",
"path": "/health",
"timeout": 5,
"type": "readiness",
"wait": 10
}
]
}
}
```
> [!NOTE]
> Only the first readiness healthcheck with a `path` property is used. Liveness, startup, and command-based healthchecks are not transformed into Traefik labels.
This will enable the docker label-based Traefik integration. All future deploys will inject the correct labels for Traefik to read and route requests to containers. Due to the docker label-based integration used by Traefik, a single deploy or rebuild will be required before requests will route successfully.
```shell
dokku ps:rebuild node-js-app
```
Any changes to domains or port mappings will also require either a deploy or rebuild.
### Starting Traefik container
Traefik can be started via the `traefik:start` command. This will start a Traefik container via the `docker compose up` command.
```shell
dokku traefik:start
```
### Stopping the Traefik container
Traefik may be stopped via the `traefik:stop` command.
```shell
dokku traefik:stop
```
The Traefik container will be stopped and removed from the system. If the container is not running, this command will do nothing.
For debugging purposes, it may be useful to show the Traefik compose config. This can be achieved via the `traefik:show-config` command.
```shell
dokku traefik:show-config
```
### Customizing the Traefik container image
While the default Traefik image is hardcoded, users may specify an alternative by setting the `image` property with the `--global` flag:
```shell
dokku traefik:set --global image traefik:v2.8
```
#### Checking the Traefik container's logs
It may be necessary to check the Traefik container's logs to ensure that Traefik is operating as expected. This can be performed with the `traefik:logs` command.
```shell
dokku traefik:logs
```
This command also supports the following modifiers:
The Traefik plugin allows you to add custom container labels to apps. These labels are injected into containers during deployment and can be used to configure Traefik behavior beyond what the plugin provides by default.
Refer to the upstream [Traefik](https://doc.traefik.io/traefik/) documentation for more information on what labels are available.
This will add the label `traefik.directive=value` to the app's containers. After adding a label, you will need to rebuild or redeploy the app for the label to be applied to running containers.
This will remove the specified label from the app. After removing a label, you will need to rebuild or redeploy the app for the change to be applied to running containers.
The traefik plugin only supports automatic ssl certificates from it's letsencrypt integration. Managed certificates provided by the `certs` plugin are ignored.
The letsencrypt integration is set to the production letsencrypt server by default. To change this, set the `letsencrypt-server` property with the `--global` flag:
By default, Traefik uses TLS-ALPN-01 challenge for obtaining certificates. To switch to DNS-01 challenge mode (useful for wildcard certificates or when port 443 is not accessible), you need to:
3. Configure the required environment variables for your DNS provider. Each DNS provider requires specific environment variables. The variable names should be prefixed with `dns-provider-`:
The `dns-provider-` prefix will be stripped and the variable name will be uppercased when passed to the Traefik container. For example, `dns-provider-cf_api_email` becomes `CF_API_EMAIL`.
After configuring, the Traefik container will need to be restarted and apps will need to be rebuilt.
Refer to the [Traefik DNS Challenge documentation](https://doc.traefik.io/traefik/https/acme/#dnschallenge) for the list of supported DNS providers and their required environment variables.
After enabling, the Traefik container will need to be restarted.
#### Enabling api basic auth
Users enabling either the api or dashboard are encouraged to enable basic auth. This will apply _only_ to the api/dashboard, and not to apps. To enable, set the `basic-auth-username` and `basic-auth-password` properties with the `--global` flag:. Both must be set or basic auth will not be enabled.
After enabling, the Traefik container will need to be restarted.
#### Customizing the api hostname
The hostname used for the api and dashboard is set to `traefik.dokku.me` by default. It can be customized by setting the `api-vhost` property with the `--global` flag:
```shell
dokku traefik:set --global api-vhost lb.dokku.me
```
After enabling, the Traefik container will need to be restarted.
## Displaying Traefik reports for an app
You can get a report about the app's Traefik config using the `traefik:report` command:
