github/dokku
0
0
Fork 0
Code Issues Pull Requests Actions 1 Packages Projects Releases Wiki Activity

Merge pull request #5295 from dokku/caddy-proxy

Browse Source 
Add an official caddy proxy implementation
This commit is contained in:
Jose Diaz-Gonzalez
2022-08-10 16:08:08 -04:00
committed by GitHub
parent 8b2afbadc2 d749a400a2
commit 6a3933213c
25 changed files with 799 additions and 7 deletions
Download Patch File Download Diff File Expand all files Collapse all files

7
docs/appendices/0.28.0-migration-guide.md
View File

@@ -16,3 +16,10 @@ All users are encouraged to install Dokku via the [Docker-based installation met
## Deprecations
Ubuntu 18.04 is now a deprecated installation target. The operating system will be considered EOL by Canonical in April 2023. Users are encouraged to upgrade to Ubuntu 22.04 or consider switching their instllation method to the [Docker-based installation method](/docs/getting-started/install/docker.md) to avoid any disruption in usage.
## Additions
New in 0.28.0 are the Caddy and Traefik plugins. As community plugins wrapping these proxies exist, users should:
- Recommended: Uninstall the community plugin in question and switch all config to the new plugins.
- Upgrade the community plugin to a version that does not use the `proxy:set` value of `caddy` or `traefik`.

198
docs/networking/proxies/caddy.md Normal file
View File

@@ -0,0 +1,198 @@
# Caddy Proxy
> New as of 0.28.0
Dokku provides integration with the [Caddy](https://caddyserver.com/) proxy service by utilizing the Docker label-based integration implemented by Caddy.
```
caddy:report [<app>] [<flag>] # Displays a caddy report for one or more apps
caddy:logs [--num num] [--tail] # Display caddy log output
caddy:set <app> <property> (<value>) # Set or clear an caddy property for an app
caddy:show-config <app> # Display caddy compose config
caddy:start # Starts the caddy server
caddy:stop # Stops the caddy server
```
## 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 Caddy.
The Caddy plugin has specific rules for routing requests:
- Caddy integration is exposed via docker labels attached to containers. Changes in labels require either app deploys or rebuilds.
- While Caddy will respect labels associated with other containers, only `web` containers have Caddy labels injected by the plugin.
- Only `http:80` and `https:443` port mappings are supported.
- Caddy will automatically enable SSL if the letsencrypt email property is set. SSL will be disabled otherwise.
- If no `http:80` mapping is found, the first `http` port mapping is used for http requests.
- If no `https:443` mapping is found, the first `https` port mapping is used for https requests.
- If no `https` mapping is found, the container port from `http:80` will be used for https requests.
- Requests are routed as soon as the container is running and passing healthchecks.
### Switching to Caddy
To use the Caddy plugin, use the `proxy:set` command for the app in question:
```shell
dokku proxy:set node-js-app caddy
```
This will enable the docker label-based Caddy integration. All future deploys will inject the correct labels for Caddy to read and route requests to containers. Due to the docker label-based integration used by Caddy, 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 Caddy container
Caddy can be started via the `caddy:start` command. This will start a Caddy container via the `docker compose up` command.
```shell
dokku caddy:start
```
### Stopping the Caddy container
Caddy may be stopped via the `caddy:stop` command.
```shell
dokku caddy:stop
```
The Caddy container will be stopped and removed from the system. If the container is not running, this command will do nothing.
### Showing the Caddy compose config
For debugging purposes, it may be useful to show the Caddy compose config. This can be achieved via the `caddy:show-config` command.
```shell
dokku caddy:show-config
```
### Customizing the Caddy container image
While the default Caddy image is hardcoded, users may specify an alternative by setting the `image` property with the `--global` flag:
```shell
dokku caddy:set --global image lucaslorentz/caddy-docker-proxy:2.7
```
#### Checking the Caddy container's logs
It may be necessary to check the Caddy container's logs to ensure that Caddy is operating as expected. This can be performed with the `caddy:logs` command.
```shell
dokku caddy: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 caddy: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 Caddy log level
Caddy log output is set to `ERROR` by default. It may be changed by setting the `log-level` property with the `--global` flag:
```shell
dokku caddy:set --global log-level DEBUG
```
After modifying, the Caddy container will need to be restarted.
### SSL Configuration
The caddy 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 caddy:set --global letsencrypt-email automated@dokku.sh
```
After enabling, the Caddy 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 caddy:set --global letsencrypt-server https://acme-staging-v02.api.letsencrypt.org/directory
```
After enabling, the Caddy container will need to be restarted and apps will need to be rebuilt to retrieve certificates from the new server.
### Using Caddy's Internal TLS server
To switch to Caddy's internal TLS server for certificate provisioning, set the `tls-internal` property. This can only be set on a per-app basis.
```shell
dokku caddy:set node-js-app tls-internal true
```
## Displaying Caddy reports for an app
You can get a report about the app's Caddy config using the `caddy:report` command:
```shell
dokku caddy:report
```
```
=====> node-js-app caddy information
Caddy image: lucaslorentz/caddy-docker-proxy:2.7
Caddy letsencrypt email:
Caddy letsencrypt server:
Caddy log level: ERROR
Caddy polling interval: 5s
Caddy tls internal: false
=====> python-app caddy information
Caddy image: lucaslorentz/caddy-docker-proxy:2.7
Caddy letsencrypt email:
Caddy letsencrypt server:
Caddy log level: ERROR
Caddy polling interval: 5s
Caddy tls internal: false
=====> ruby-app caddy information
Caddy image: lucaslorentz/caddy-docker-proxy:2.7
Caddy letsencrypt email:
Caddy letsencrypt server:
Caddy log level: ERROR
Caddy polling interval: 5s
Caddy tls internal: false
```
You can run the command for a specific app also.
```shell
dokku caddy:report node-js-app
```
```
=====> node-js-app caddy information
Caddy image: lucaslorentz/caddy-docker-proxy:2.7
Caddy letsencrypt email:
Caddy letsencrypt server:
Caddy log level: ERROR
Caddy polling interval: 5s
Caddy tls internal: false
```
You can pass flags which will output only the value of the specific information you want. For example:
```shell
dokku caddy:report node-js-app --caddy-image
```

8
docs/networking/proxies/nginx.md
View File

@@ -1,4 +1,4 @@
# Nginx Configuration
# Nginx Proxy
Dokku uses nginx as its server for routing requests to specific applications. By default, access and error logs are written for each app to `/var/log/nginx/${APP}-access.log` and `/var/log/nginx/${APP}-error.log` respectively
@@ -15,6 +15,8 @@ nginx:validate-config [<app>] [--clean] # Validates and optionally cleans up in
## 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.
### Request Proxying
By default, the `web` process is the only process proxied by the nginx proxy implementation. Proxying to other process types may be handled by a custom `nginx.conf.sigil` file, as generally described [below](/docs/networking/proxies/nginx.md#customizing-the-nginx-configuration)
@@ -23,6 +25,8 @@ Nginx will proxy the requests in a [round-robin balancing fashion](http://nginx.
### Starting nginx
> New as of 0.28.0
The nginx server can be started via `nginx:start`.
```shell
@@ -31,6 +35,8 @@ dokku nginx:start
### Stopping nginx
> New as of 0.28.0
The nginx server can be stopped via `nginx:stop`.
```shell

26
docs/networking/proxies/traefik.md
View File

@@ -1,4 +1,6 @@
# Traefik Configuration
# Traefik Proxy
> New as of 0.28.0
Dokku provides integration with the [Traefik](https://traefik.io/) proxy service by utilizing the Docker label-based integration implemented by Traefik.
@@ -21,7 +23,7 @@ The Traefik plugin has specific rules for routing requests:
- While Traefik will respect labels associated with other containers, only `web` containers have Traefik labels injected by the plugin.
- Only `http:80` and `https:443` port mappings are supported.
- If no `http:80` mapping is found, the first `http` port mapping is used for http requests.
- If no `https:443` mapping is found, the first `https` port mapping is used for http requests.
- If no `https:443` mapping is found, the first `https` port mapping is used for https requests.
- If no `https` mapping is found, the container port from `http:80` will be used for https requests.
- Requests are routed as soon as the container is running and passing healthchecks.
@@ -108,7 +110,11 @@ dokku traefik:set --global log-level DEBUG
After modifying, the Traefik container will need to be restarted.
### Enabling letsencrypt integration
### SSL Configuration
The traefik 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:
@@ -118,6 +124,16 @@ dokku traefik:set --global letsencrypt-email automated@dokku.sh
After enabling, apps will need to be rebuilt and the Traefik container will need to be restarted. 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 traefik:set --global letsencrypt-server https://acme-staging-v02.api.letsencrypt.org/directory
```
After enabling, the Traefik container will need to be restarted and apps will need to be rebuilt to retrieve certificates from the new server.
### API Access
Traefik exposes an API and Dashboard, which Dokku disables by default for security reasons. It can be exposed and customized as described below.
@@ -184,6 +200,7 @@ dokku traefik:report
Traefik dashboard enabled: false
Traefik image: traefik:v2.8
Traefik letsencrypt email:
Traefik letsencrypt server:
Traefik log level: ERROR
=====> python-app traefik information
Traefik api enabled: false
@@ -193,6 +210,7 @@ dokku traefik:report
Traefik dashboard enabled: false
Traefik image: traefik:v2.8
Traefik letsencrypt email:
Traefik letsencrypt server:
Traefik log level: ERROR
=====> ruby-app traefik information
Traefik api enabled: false
@@ -202,6 +220,7 @@ dokku traefik:report
Traefik dashboard enabled: false
Traefik image: traefik:v2.8
Traefik letsencrypt email:
Traefik letsencrypt server:
Traefik log level: ERROR
```
@@ -220,6 +239,7 @@ dokku traefik:report node-js-app
Traefik dashboard enabled: false
Traefik image: traefik:v2.8
Traefik letsencrypt email:
Traefik letsencrypt server:
Traefik log level: ERROR
```

3
docs/template.html
View File

@@ -47,7 +47,7 @@
<link rel="preconnect" href="https://fonts.googleapis.com">
<link rel="preconnect" href="https://fonts.gstatic.com" crossorigin>
<link href="https://fonts.googleapis.com/css2?family=Lato:wght@400;700;900&display=swap" rel="stylesheet">
<link href="https://cdn.jsdelivr.net/gh/dokku/dokku@v0.27.10/docs/assets/style.css" rel="stylesheet">
<!-- <link href="./assets/style.css" rel="stylesheet"> -->
<link href="https://cdnjs.cloudflare.com/ajax/libs/font-awesome/4.5.0/css/font-awesome.min.css" rel="stylesheet">
@@ -175,6 +175,7 @@
<a href="#" class="list-group-item disabled">Proxy Configuration</a>
<a href="/{{NAME}}/networking/proxy-management/" class="list-group-item">Proxy Management</a>
<a href="/{{NAME}}/networking/proxies/caddy/" class="list-group-item">Caddy Proxy</a>
<a href="/{{NAME}}/networking/proxies/nginx/" class="list-group-item">Nginx Proxy</a>
<a href="/{{NAME}}/networking/proxies/traefik/" class="list-group-item">Traefik Proxy</a>