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

docs: use github admonitions

Browse Source 
These still need to be properly parsed.
This commit is contained in:
Jose Diaz-Gonzalez
2023-08-19 14:24:12 -04:00
parent 5dd78e2b86
commit d61d91cf87
47 changed files with 277 additions and 89 deletions
Download Patch File Download Diff File Expand all files Collapse all files

4
docs/networking/proxies/caddy.md
View File

@@ -1,5 +1,6 @@
# Caddy Proxy
> [!IMPORTANT]
> 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.
@@ -19,7 +20,8 @@ Using the `caddy` plugin integration requires the `docker-compose-plugin` for Do
## 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.
> [!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:

4
docs/networking/proxies/haproxy.md
View File

@@ -1,5 +1,6 @@
# 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).
@@ -19,7 +20,8 @@ Using the `haproxy` plugin integration requires the `docker-compose-plugin` for
## 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.
> [!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:

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

@@ -15,7 +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.
> [!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
@@ -23,10 +24,12 @@ By default, the `web` process is the only process proxied by the nginx proxy imp
Nginx will proxy the requests in a [round-robin balancing fashion](http://nginx.org/en/docs/http/ngx_http_upstream_module.html#upstream) to the different deployed (scaled) containers running the `web` proctype. This way, the host's resources can be fully leveraged for single-threaded applications (e.g. `dokku ps:scale node-js-app web=4` on a 4-core machine).
> Note: Due to how the plugin is implemented, if an app successfully starts up `web` containers but fails to deploy some other containers, nginx may eventually stop routing requests. Users should revert their code in these cases, or manually trigger `dokku proxy:build-config $APP` in order to ensure requests route to the new web containers.
> [!NOTE]
> Due to how the plugin is implemented, if an app successfully starts up `web` containers but fails to deploy some other containers, nginx may eventually stop routing requests. Users should revert their code in these cases, or manually trigger `dokku proxy:build-config $APP` in order to ensure requests route to the new web containers.
### Starting nginx
> [!IMPORTANT]
> New as of 0.28.0
The nginx server can be started via `nginx:start`.
@@ -37,6 +40,7 @@ dokku nginx:start
### Stopping nginx
> [!IMPORTANT]
> New as of 0.28.0
The nginx server can be stopped via `nginx:stop`.
@@ -47,9 +51,11 @@ dokku nginx:stop
### Binding to specific addresses
> [!IMPORTANT]
> New as of 0.19.2
> Note: Changing this value globally or on a per-app basis will require rebuilding the nginx config via the `proxy:build-config` command.
> [!NOTE]
> Changing this value globally or on a per-app basis will require rebuilding the nginx config via the `proxy:build-config` command.
By default, nginx will listen to all interfaces (`[::]` for IPv6, `0.0.0.0` for IPv4) when proxying requests to applications. This may be changed using the `bind-address-ipv4` and `bind-address-ipv6` properties. This is useful in cases where the proxying should be internal to a network or if there are multiple network interfaces that should respond with different content.
@@ -65,15 +71,18 @@ dokku nginx:set node-js-app bind-address-ipv4
dokku nginx:set node-js-app bind-address-ipv6
```
> Warning: Validation is not performed on either value.
> [!WARNING]
> Validation is not performed on either value.
Users with apps that contain a custom `nginx.conf.sigil` file will need to modify the files to respect the new `NGINX_BIND_ADDRESS_IPV4` and `NGINX_BIND_ADDRESS_IPV6` variables.
### HSTS Header
> [!IMPORTANT]
> New as of 0.20.0
> Note: Changing this value globally or on a per-app basis will require rebuilding the nginx config via the `proxy:build-config` command.
> [!NOTE]
> Changing this value globally or on a per-app basis will require rebuilding the nginx config via the `proxy:build-config` command.
If SSL certificates are present, HSTS will be automatically enabled. It can be toggled via `nginx:set`:
@@ -93,7 +102,8 @@ Beware that if you enable the header and a subsequent deploy of your application
#### Globally disabling the HSTS Header
> Note: Changing this value globally or on a per-app basis will require rebuilding the nginx config via the `proxy:build-config` command.
> [!NOTE]
> Changing this value globally or on a per-app basis will require rebuilding the nginx config via the `proxy:build-config` command.
HSTS Header can be disabled for all apps by setting the `hsts` property to false after passing the `--global` flag to `nginx:set`.
@@ -145,7 +155,8 @@ dokku nginx:set node-js-app x-forwarded-ssl
### Checking access logs
> Note: Changing this value globally or on a per-app basis will require rebuilding the nginx config via the `proxy:build-config` command.
> [!NOTE]
> Changing this value globally or on a per-app basis will require rebuilding the nginx config via the `proxy:build-config` command.
You may check nginx access logs via the `nginx:access-logs` command. This assumes that app access logs are being stored in `/var/log/nginx/$APP-access.log`, as is the default in the generated `nginx.conf`.
@@ -175,9 +186,11 @@ dokku nginx:error-logs node-js-app -t
### Changing log path
> [!IMPORTANT]
> New as of 0.20.1
> Note: Changing this value globally or on a per-app basis will require rebuilding the nginx config via the `proxy:build-config` command.
> [!NOTE]
> Changing this value globally or on a per-app basis will require rebuilding the nginx config via the `proxy:build-config` command.
The path to where log files are stored can be changed by calling the `nginx:set` command with the following options:
@@ -202,9 +215,11 @@ In all cases, the nginx config must be regenerated after setting the above value
### Changing log format
> [!IMPORTANT]
> New as of 0.22.0
> Note: Changing this value globally or on a per-app basis will require rebuilding the nginx config via the `proxy:build-config` command.
> [!NOTE]
> Changing this value globally or on a per-app basis will require rebuilding the nginx config via the `proxy:build-config` command.
The format of the access log can be changed by calling the `nginx:set` command as follows:
@@ -245,9 +260,11 @@ dokku proxy:build-config node-js-app
### Specifying a read timeout
> [!IMPORTANT]
> New as of 0.21.0
> Note: Changing this value globally or on a per-app basis will require rebuilding the nginx config via the `proxy:build-config` command.
> [!NOTE]
> Changing this value globally or on a per-app basis will require rebuilding the nginx config via the `proxy:build-config` command.
When proxying requests to your applications, it may be useful to specify a proxy read timeout. This can be done via the `nginx:set` command as follows:
@@ -267,9 +284,11 @@ In all cases, the nginx config must be regenerated after setting the above value
### Specifying a custom client_max_body_size
> [!IMPORTANT]
> New as of 0.23.0
> Note: Changing this value globally or on a per-app basis will require rebuilding the nginx config via the `proxy:build-config` command.
> [!NOTE]
> Changing this value globally or on a per-app basis will require rebuilding the nginx config via the `proxy:build-config` command.
Users can override the default `client_max_body_size` value - which limits file uploads - via `nginx:set`. Changing this value will only apply to every `server` stanza of the default `nginx.conf.sigil`; users of custom `nginx.conf.sigil` files must update their templates to support the new value.
@@ -309,7 +328,8 @@ As app nginx configs are actually executed within a shared context, it is possib
The `nginx:validate-config` command also takes an optional `--clean` flag. If specified, invalid nginx configs will be removed.
> Warning: Invalid app nginx config's will be removed _even if_ the config is valid in the global server context.
> [!WARNING]
> Invalid app nginx config's will be removed _even if_ the config is valid in the global server context.
```shell
dokku nginx:validate-config --clean
@@ -323,6 +343,7 @@ dokku nginx:validate-config node-js-app --clean
### Customizing the nginx configuration
> [!IMPORTANT]
> New as of 0.5.0
Dokku uses a templating library by the name of [sigil](https://github.com/gliderlabs/sigil) to generate nginx configuration for each app. This may be overriden by committing the [default configuration template](https://github.com/dokku/dokku/blob/master/plugins/nginx-vhosts/templates/nginx.conf.sigil) to a file named `nginx.conf.sigil` in the root of the app repository.
@@ -352,7 +373,8 @@ dokku nginx:set --global nginx-conf-sigil-path
#### Disabling custom nginx config
> Note: Changing this value globally or on a per-app basis will require rebuilding the nginx config via the `proxy:build-config` command.
> [!NOTE]
> Changing this value globally or on a per-app basis will require rebuilding the nginx config via the `proxy:build-config` command.
While enabled by default, using a custom nginx config can be disabled via `nginx:set`. This may be useful in cases where you do not want to allow users to override any higher-level customization of app nginx config.
@@ -383,7 +405,8 @@ Unsetting this value is the same as enabling custom nginx config usage.
Finally, each process type has it's network listeners - a list of IP:PORT pairs for the respective app containers - exposed via an `.DOKKU_APP_${PROCESS_TYPE}_LISTENERS` variable - the `PROCESS_TYPE` will be upper-cased with hyphens transformed into underscores. Users can use the new variables to expose non-web processes via the nginx proxy.
> Note: Application environment variables are available for use in custom templates. To do so, use the form of `{{ var "FOO" }}` to access a variable named `FOO`.
> [!NOTE]
> Application environment variables are available for use in custom templates. To do so, use the form of `{{ var "FOO" }}` to access a variable named `FOO`.
#### Customizing via configuration files included by the default templates
@@ -436,7 +459,8 @@ These are provided as an alternative to the generic Nginx error page, are shared
By default, Dokku will route any received request with an unknown HOST header value to the lexicographically first site in the nginx config stack. This means that accessing the dokku server via its IP address or a bogus domain name may return a seemingly random website.
> Warning: some versions of Nginx may create a default site when installed. This site is simply a static page which says "Welcome to Nginx", and if this default site is enabled, Nginx will not route any requests with an unknown HOST header to Dokku. If you want Dokku to receive all requests, run the following commands:
> [!WARNING]
> some versions of Nginx may create a default site when installed. This site is simply a static page which says "Welcome to Nginx", and if this default site is enabled, Nginx will not route any requests with an unknown HOST header to Dokku. If you want Dokku to receive all requests, run the following commands:
>
> ```
> rm /etc/nginx/sites-enabled/default

4
docs/networking/proxies/openresty.md
View File

@@ -1,5 +1,6 @@
# OpenResty Proxy
> [!IMPORTANT]
> New as of 0.31.0
Dokku can provide integration with the [OpenResty](https://openresty.org/) proxy service by utilizing the Docker label-based integration implemented by [openresty-docker-proxy](https://github.com/dokku/openresty-docker-proxy).
@@ -19,7 +20,8 @@ Using the `openresty` plugin integration requires the `docker-compose-plugin` fo
## 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 OpenResty.
> [!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 OpenResty.
The OpenResty plugin has specific rules for routing requests:

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

@@ -1,5 +1,6 @@
# Traefik Proxy
> [!IMPORTANT]
> 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.
@@ -19,7 +20,8 @@ Using the `traefik` plugin integration requires the `docker-compose-plugin` for
## 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 Traefik.
> [!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 Traefik.
The Traefik plugin has specific rules for routing requests:
@@ -154,7 +156,8 @@ Traefik exposes an API and Dashboard, which Dokku disables by default for securi
#### Enabling the api
> Warning: Users enabling the dashboard should also enable api basic auth.
> [!WARNING]
> Users enabling the dashboard should also enable api basic auth.
By default, the api is disabled. To enable, set the `api` property with the `--global` flag:
@@ -166,7 +169,8 @@ After enabling, the Traefik container will need to be restarted.
#### Enabling the dashboard
> Warning: Users enabling the dashboard should also enable api basic auth.
> [!WARNING]
> Users enabling the dashboard should also enable api basic auth.
By default, the dashboard is disabled. To enable, set the `dashboard` property with the `--global` flag: