Mirrors/dokku
1
0
Fork 0
mirror of https://github.com/dokku/dokku.git synced 2026-05-18 05:05:46 +02:00
Code Issues 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

3
docs/networking/dns.md
View File

@@ -1,6 +1,7 @@
# DNS Configuration
> Note: This is a work in progress.
> [!NOTE]
> This is a work in progress.
## DNS Versions

13
docs/networking/network.md
View File

@@ -1,5 +1,6 @@
# Network Management
> [!IMPORTANT]
> New as of 0.11.0, Enhanced in 0.20.0
```
@@ -20,6 +21,7 @@ The Network plugin allows developers to abstract the concept of container networ
### Listing networks
> [!IMPORTANT]
> New as of 0.20.0, Requires Docker 1.21+
You can easily list all available networks using the `network:list` command:
@@ -51,6 +53,7 @@ test-network
### Creating a network
> [!IMPORTANT]
> New as of 0.20.0, Requires Docker 1.21+
Docker networks can be created via the `network:create` command. Executing this command will create an attachable `bridge` network. This can be used to route requests between containers without going through any public network.
@@ -67,6 +70,7 @@ Specifying other additional flags or other types of networks can be created dire
### Destroying a network
> [!IMPORTANT]
> New as of 0.20.0, Requires Docker 1.21+
A Docker network without any associated containers may be destroyed via the `network:destroy` command. Docker will refuse to destroy networks that have containers attached.
@@ -95,6 +99,7 @@ dokku --force network:destroy test-network
### Checking if a network exists
> [!IMPORTANT]
> New as of 0.20.0, Requires Docker 1.21+
For CI/CD pipelines, it may be useful to see if an network exists before creating a new network. You can do so via the `network:exists` command:
@@ -111,6 +116,7 @@ The `network:exists` command will return non-zero if the network does not exist,
### Checking network info
> [!IMPORTANT]
> New as of 0.20.0, Requires Docker 1.21+
Network information can be retrieved via the `network:info` command. This is a slightly different version of the `docker network` command.
@@ -155,6 +161,7 @@ Only a single `$IP:$PORT` combination can be routed to for a given app, and that
### Attaching an app to a network
> [!IMPORTANT]
> New as of 0.20.0, Requires Docker 1.21+
Apps will default to being associated with the default `bridge` network or a network specified by the `initial-network` network property. Additionally, an app can be attached to `attachable` networks by changing the `attach-post-create` or `attach-post-deploy` network properties when using the [docker-local scheduler](/docs/deployment/schedulers/docker-local.md). A change in these values will require an app deploy or rebuild.
@@ -206,7 +213,8 @@ dokku network:set --global initial-network
#### Network Aliases
> Note: This feature is only available when an app has been attached to a network other than the default `bridge` network.
> [!NOTE]
> This feature is only available when an app has been attached to a network other than the default `bridge` network.
When a container created for a deployment is being attached to a network - regardless of which network property was used - a network alias of the pattern `APP.PROC_TYPE` will be added to all containers. This can be used to load-balance requests between containers. For an application named `node-js-app` with a process type of web, the network alias - or resolvable DNS record within the network - will be:
@@ -292,7 +300,8 @@ Whatever the reason, the semantics of the two network hooks are important and ar
- Use case: When another container on the network is already running and needed by this container.
- Example: A key-value store exposing itself to all your apps may be on the `initial-network`.
> Warning: If the attachment fails during the `running` container state, this may result in your application failing to respond to proxied requests once older containers are removed.
> [!WARNING]
> If the attachment fails during the `running` container state, this may result in your application failing to respond to proxied requests once older containers are removed.
### Rebuilding network settings

10
docs/networking/port-management.md
View File

@@ -1,5 +1,6 @@
# Port Management
> [!IMPORTANT]
> New as of 0.31.0, replaces the previous `proxy:ports*` commands
```
@@ -12,7 +13,8 @@ ports:set <app> <scheme>:<host-port>:<container-port> [<scheme>:<host-port>:<con
## Usage
> Warning: Mapping alternative ports may conflict with the active firewall installed on your server or hosting provider. Such software includes - but is not limited to - AWS Security Groups, iptables, and UFW. Please consult the documentation for those softwares as applicable.
> [!WARNING]
> Mapping alternative ports may conflict with the active firewall installed on your server or hosting provider. Such software includes - but is not limited to - AWS Security Groups, iptables, and UFW. Please consult the documentation for those softwares as applicable.
>
> Users should also avoid setting the `PORT` environment variable. Dokku will use port mappings to set this value. Overriding this manually may cause issues in application routing.
@@ -20,7 +22,8 @@ You can now configure `host -> container` port mappings with the `ports:*` comma
By default, buildpack apps and dockerfile apps **without** explicitly exposed ports (i.e. using the `EXPOSE` directive) will be configured with a listener on port `80` (and additionally a listener on 443 if ssl is enabled) that will proxy to the application container on port `5000`. Dockerfile apps **with** explicitly exposed ports will be configured with a listener on each exposed port and will proxy to that same port of the deployed application container.
> Note: This default behavior **will not** be automatically changed on subsequent pushes and must be manipulated with the `ports:*` commands detailed below.
> [!NOTE]
> This default behavior **will not** be automatically changed on subsequent pushes and must be manipulated with the `ports:*` commands detailed below.
### Port Scheme
@@ -138,7 +141,8 @@ dokku ports:remove node-js-app http:80
## Port management by Deployment Method
> Warning: If you set a port map but _do not have a global domain set_, Dokku will reset that map upon first deployment.
> [!WARNING]
> If you set a port map but _do not have a global domain set_, Dokku will reset that map upon first deployment.
### Buildpacks

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:

3
docs/networking/proxy-management.md
View File

@@ -1,5 +1,6 @@
# Proxy Management
> [!IMPORTANT]
> New as of 0.5.0, Enhanced in 0.6.0
```
@@ -43,6 +44,7 @@ dokku proxy:build-config --all --parallel -1
### Clearing the generated proxy config
> [!IMPORTANT]
> New as of 0.27.0
Generated proxy configurations can also be cleared using the `proxy:clear-config` command.
@@ -61,6 +63,7 @@ Clearing a proxy configuration has different effects depending on the proxy plug
### Displaying proxy reports for an app
> [!IMPORTANT]
> New as of 0.8.1
You can get a report about the app's proxy status using the `proxy:report` command: