8742f688e3
Renames the existing `## Internal properties` umbrella section to `## Properties` across all plugin docs and adds a new `### Settable properties` subsection enumerating every property accepted by each plugin's `:set` command. Each row lists scope, default, the actual `:report` flag shapes that surface the value, and a one-line description. The buildpacks plugin is included even though it uses `:set-property`, with a note in the subsection clarifying the legacy command name. Property lists, scopes, and report flags were verified against plugin source and the live dokku binary.
269 lines
10 KiB
Markdown
269 lines
10 KiB
Markdown
# Haproxy Proxy
|
|
|
|
> [!IMPORTANT]
|
|
> New as of 0.28.0
|
|
|
|
Dokku provides integration with the [Haproxy](http://www.haproxy.org) proxy service by utilizing the Docker label-based integration implemented by [EasyHaproxy](https://github.com/byjg/docker-easy-haproxy).
|
|
|
|
```
|
|
haproxy:report [<app>] [<flag>] # Displays a haproxy report for one or more apps
|
|
haproxy:logs [--num num] [--tail] # Display haproxy log output
|
|
haproxy:set <app> <property> (<value>) # Set or clear an haproxy property for an app
|
|
haproxy:show-config <app> # Display haproxy compose config
|
|
haproxy:start # Starts the haproxy server
|
|
haproxy:stop # Stops the haproxy server
|
|
```
|
|
|
|
## Requirements
|
|
|
|
Using the `haproxy` 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`.
|
|
|
|
## Usage
|
|
|
|
> [!WARNING]
|
|
> 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 Haproxy.
|
|
|
|
The Haproxy plugin has specific rules for routing requests:
|
|
|
|
- Haproxy integration is exposed via docker labels attached to containers. Changes in labels require either app deploys or rebuilds.
|
|
- While Haproxy will respect labels associated with other containers, only `web` containers have Haproxy labels injected by the plugin.
|
|
- Only `http:80` and `https:443` port mappings are supported at this time.
|
|
- Requests are routed as soon as the container is running and passing healthchecks.
|
|
|
|
### Switching to Haproxy
|
|
|
|
To use the Haproxy plugin, use the `proxy:set` command for the app in question:
|
|
|
|
```shell
|
|
dokku proxy:set node-js-app type haproxy
|
|
```
|
|
|
|
This will enable the docker label-based Haproxy integration. All future deploys will inject the correct labels for Haproxy to read and route requests to containers. Due to the docker label-based integration used by Haproxy, 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 Haproxy container
|
|
|
|
Haproxy can be started via the `haproxy:start` command. This will start a Haproxy container via the `docker compose up` command.
|
|
|
|
```shell
|
|
dokku haproxy:start
|
|
```
|
|
|
|
### Stopping the Haproxy container
|
|
|
|
Haproxy may be stopped via the `haproxy:stop` command.
|
|
|
|
```shell
|
|
dokku haproxy:stop
|
|
```
|
|
|
|
The Haproxy container will be stopped and removed from the system. If the container is not running, this command will do nothing.
|
|
|
|
### Showing the Haproxy compose config
|
|
|
|
For debugging purposes, it may be useful to show the Haproxy compose config. This can be achieved via the `haproxy:show-config` command.
|
|
|
|
```shell
|
|
dokku haproxy:show-config
|
|
```
|
|
|
|
### Customizing the Haproxy container image
|
|
|
|
While the default Haproxy image is hardcoded, users may specify an alternative by setting the `image` property with the `--global` flag:
|
|
|
|
```shell
|
|
dokku haproxy:set --global image byjg/easy-haproxy:4.0.0
|
|
```
|
|
|
|
#### Checking the Haproxy container's logs
|
|
|
|
It may be necessary to check the Haproxy container's logs to ensure that Haproxy is operating as expected. This can be performed with the `haproxy:logs` command.
|
|
|
|
```shell
|
|
dokku haproxy:logs
|
|
```
|
|
|
|
This command also supports the following modifiers:
|
|
|
|
```shell
|
|
--num NUM # the number of lines to display
|
|
--tail # continually stream logs
|
|
```
|
|
|
|
You can use these modifiers as follows:
|
|
|
|
```shell
|
|
dokku haproxy:logs --tail --num 10
|
|
```
|
|
|
|
The above command will show logs continually from the vector container, with an initial history of 10 log lines
|
|
|
|
### Changing the Haproxy log level
|
|
|
|
Haproxy log output is set to `ERROR` by default. It may be changed by setting the `log-level` property with the `--global` flag:
|
|
|
|
```shell
|
|
dokku haproxy:set --global log-level DEBUG
|
|
```
|
|
|
|
After modifying, the Haproxy container will need to be restarted.
|
|
|
|
### Changing the Haproxy refresh interval
|
|
|
|
Haproxy polls the Docker API for label changes every `10` seconds by default. The interval may be changed by setting the `refresh-conf` property with the `--global` flag:
|
|
|
|
```shell
|
|
dokku haproxy:set --global refresh-conf 5
|
|
```
|
|
|
|
The `refresh-conf` property is global-only and cannot be set on a per-app basis. Setting an empty value will reset it to the default. After modifying, the Haproxy container will need to be restarted.
|
|
|
|
### Label Management
|
|
|
|
The Haproxy plugin allows you to add custom container labels to apps. These labels are injected into containers during deployment and can be used to configure Haproxy behavior beyond what the plugin provides by default.
|
|
|
|
Refer to the upstream [EasyHaproxy](https://github.com/byjg/docker-easy-haproxy) documentation for more information on what labels are available.
|
|
|
|
#### Adding a label
|
|
|
|
To add a custom container label to an app, use the `haproxy:labels:add` command:
|
|
|
|
```shell
|
|
dokku haproxy:labels:add node-js-app haproxy.directive value
|
|
```
|
|
|
|
This will add the label `haproxy.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.
|
|
|
|
```shell
|
|
dokku ps:rebuild node-js-app
|
|
```
|
|
|
|
#### Removing a label
|
|
|
|
To remove a custom container label from an app, use the `haproxy:labels:remove` command:
|
|
|
|
```shell
|
|
dokku haproxy:labels:remove node-js-app haproxy.directive
|
|
```
|
|
|
|
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.
|
|
|
|
```shell
|
|
dokku ps:rebuild node-js-app
|
|
```
|
|
|
|
#### Showing labels
|
|
|
|
To view all custom container labels for an app, use the `haproxy:labels:show` command:
|
|
|
|
```shell
|
|
dokku haproxy:labels:show node-js-app
|
|
```
|
|
|
|
To view a specific label value, provide the label name:
|
|
|
|
```shell
|
|
dokku haproxy:labels:show node-js-app haproxy.directive
|
|
```
|
|
|
|
### SSL Configuration
|
|
|
|
The haproxy plugin only supports automatic ssl certificates from it's letsencrypt integration. Managed certificates provided by the `certs` plugin are ignored.
|
|
|
|
#### Enabling letsencrypt integration
|
|
|
|
By default, letsencrypt is disabled and https port mappings are ignored. To enable, set the `letsencrypt-email` property with the `--global` flag:
|
|
|
|
```shell
|
|
dokku haproxy:set --global letsencrypt-email automated@dokku.sh
|
|
```
|
|
|
|
After enabling, the Haproxy container will need to be restarted and apps will need to be rebuilt. All http requests will then be redirected to https.
|
|
|
|
#### Customizing the letsencrypt server
|
|
|
|
The letsencrypt integration is set to the production letsencrypt server by default. To change this, set the `letsencrypt-server` property with the `--global` flag:
|
|
|
|
```shell
|
|
dokku haproxy:set --global letsencrypt-server https://acme-staging-v02.api.letsencrypt.org/directory
|
|
```
|
|
|
|
After enabling, the Haproxy container will need to be restarted and apps will need to be rebuilt to retrieve certificates from the new server.
|
|
|
|
## Displaying Haproxy reports for an app
|
|
|
|
You can get a report about the app's Haproxy config using the `haproxy:report` command:
|
|
|
|
```shell
|
|
dokku haproxy:report
|
|
```
|
|
|
|
```
|
|
=====> node-js-app haproxy information
|
|
Haproxy computed image: byjg/easy-haproxy:4.0.0
|
|
Haproxy computed letsencrypt email:
|
|
Haproxy computed letsencrypt server: https://acme-v02.api.letsencrypt.org/directory
|
|
Haproxy computed log level: ERROR
|
|
Haproxy computed refresh conf: 10
|
|
Haproxy global image:
|
|
Haproxy global letsencrypt email:
|
|
Haproxy global letsencrypt server:
|
|
Haproxy global log level:
|
|
Haproxy global refresh conf:
|
|
```
|
|
|
|
The `global-<prop>` keys hold the raw global value and are empty when nothing has been set globally. The `computed-<prop>` keys hold the effective value used at deploy time, falling back to the built-in default when the global value is empty.
|
|
|
|
You can run the command for a specific app also.
|
|
|
|
```shell
|
|
dokku haproxy:report node-js-app
|
|
```
|
|
|
|
```
|
|
=====> node-js-app haproxy information
|
|
Haproxy computed image: byjg/easy-haproxy:4.0.0
|
|
Haproxy computed letsencrypt email:
|
|
Haproxy computed letsencrypt server: https://acme-v02.api.letsencrypt.org/directory
|
|
Haproxy computed log level: ERROR
|
|
Haproxy computed refresh conf: 10
|
|
Haproxy global image:
|
|
Haproxy global letsencrypt email:
|
|
Haproxy global letsencrypt server:
|
|
Haproxy global log level:
|
|
Haproxy global refresh conf:
|
|
```
|
|
|
|
You can pass flags which will output only the value of the specific information you want. For example:
|
|
|
|
```shell
|
|
dokku haproxy:report node-js-app --haproxy-computed-image
|
|
```
|
|
|
|
## Properties
|
|
|
|
### Settable properties
|
|
|
|
All haproxy properties are global only. Set with `haproxy:set --global <property> <value>`.
|
|
|
|
| Property | Scope | Default | Report flags | Description |
|
|
|---|---|---|---|---|
|
|
| `image` | global only | _parsed from `plugins/haproxy-vhosts/Dockerfile`_ | `--haproxy-global-image`, `--haproxy-computed-image` | Docker image used to run the Haproxy container |
|
|
| `letsencrypt-email` | global only | none | `--haproxy-global-letsencrypt-email`, `--haproxy-computed-letsencrypt-email` | Contact email enabling letsencrypt; empty disables https issuance |
|
|
| `letsencrypt-server` | global only | `https://acme-v02.api.letsencrypt.org/directory` | `--haproxy-global-letsencrypt-server`, `--haproxy-computed-letsencrypt-server` | ACME directory used when requesting certificates |
|
|
| `log-level` | global only | `ERROR` | `--haproxy-global-log-level`, `--haproxy-computed-log-level` | Haproxy log level |
|
|
| `refresh-conf` | global only | `10` | `--haproxy-global-refresh-conf`, `--haproxy-computed-refresh-conf` | Seconds between Haproxy polls of the Docker API for label changes |
|
|
|
|
### Internal properties
|
|
|
|
The following properties are not managed by `haproxy:set` but are recorded internally by the plugin:
|
|
|
|
| Property | Description | Source |
|
|
|---|---|---|
|
|
| `proxy-status` | `started`/`stopped` state of the haproxy compose project | `cmd-haproxy-start`/`cmd-haproxy-stop` in `plugins/haproxy-vhosts/command-functions` |
|