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

nginx-vhosts rewrite

Browse Source
This commit is contained in:
Michael Hobbs
2016-02-14 18:43:40 -08:00
parent 4404e145c0
commit 9842d7498b
65 changed files with 1779 additions and 1123 deletions
Download Patch File Download Diff File Expand all files Collapse all files

20
docs/appendices/0.5.0-migration-guide.md Normal file
View File

@@ -0,0 +1,20 @@
# 0.5.0 Migration Guide
## nginx-vhosts
- The nginx-vhosts template language is now [sigil](https://github.com/gliderlabs/sigil)
- No need to escape literal `$` characters (or other "bash-isms")
- Template variables are represented as {{ .VARIABLE_NAME }}
- A detailed list of template variables can be found [here](/dokku/nginx#available-template-variables)
- A custom nginx-vhosts template must be named `nginx.conf.sigil`
- The default path for this custom template is the root of your repo (i.e. `/app` in the container or `WORKDIR` if defined in a dockerfile app)
- Dokku no longer looks for this file in `/home/dokku/myapp` on the dokku server
- Check out an example template [here](/dokku/nginx/)
- Support for server-wide SSL certs have been dropped in favor of using the `certs` plugin
- `dokku certs:add myapp < certs.tar`
- All domains for an SSL-enabled app will be redirected to https by default
- This can be overridden with a custom template
- Replaced "magic" `NO_VHOST` variable with `domains:enable/disable`
- Simplified zero downtime control
- `checks:enable/disable`
## Dockerfile apps with multiple ports
- Dockerfiles with multiple `EXPOSE` clauses will get all **tcp** ports proxied by default (nginx does not support proxying udp)
- UDP can be exposed by disabling the nginx proxy with `dokku proxy:disable myapp`

14
docs/checks-examples.md
View File

@@ -1,6 +1,10 @@
# Zero Downtime Deploys
> New as of 0.3.0
```
checks <app> Show zero-downtime status
checks:disable <app> Disable zero-downtime checks
checks:enable <app> Enable zero-downtime checks
```
Following a deploy, dokku will now wait `10` seconds before routing traffic to the new container. If the container is not running after this time, then the deploy is failed and your old container will continue serving traffic. You can modify this value using the following command:
@@ -38,14 +42,10 @@ Dokku will retry the checks `5` times until the checks are successful. If all 5
dokku config:set --global DOKKU_CHECKS_ATTEMPTS=2
```
You can also choose to skip checks completely either globally or on a per-application basis:
You can also choose to skip checks completely on a per-application basis:
```shell
# globally
dokku config:set --global DOKKU_SKIP_ALL_CHECKS=true
# for APP
dokku config:set APP DOKKU_SKIP_ALL_CHECKS=true
dokku checks:disable APP
```
## Checks Examples

34
docs/deployment/ssl-configuration.md
View File

@@ -101,14 +101,40 @@ Beware that if you enable the header and a subsequent deploy of your application
## Running behind a load balancer
> New as of 0.3.17
Your application has access to the HTTP headers `X-Forwarded-Proto`, `X-Forwarded-For` and `X-Forwarded-Port`. These headers indicate the protocol of the original request (HTTP or HTTPS), the port number, and the IP address of the client making the request, respectively. The default configuration is for Nginx to set these headers.
If your server runs behind an HTTP/S load balancer, then Nginx will see all requests as coming from the load balancer. If your load balancer sets the `X-Forwarded-` headers, you can tell Nginx to pass these headers from load balancer to your application by setting the `DOKKU_SSL_TERMINATED` environment variable:
If your server runs behind an HTTP/S load balancer, then Nginx will see all requests as coming from the load balancer. If your load balancer sets the `X-Forwarded-` headers, you can tell Nginx to pass these headers from load balancer to your application by using the following [nginx custom template](/dokku/nginx/#customizing-the-nginx-configuration)
```shell
dokku config:set myapp DOKKU_SSL_TERMINATED=1
server {
listen [::]:{{ .NGINX_PORT }};
listen {{ .NGINX_PORT }};
server_name {{ .NOSSL_SERVER_NAME }};
access_log /var/log/nginx/{{ .APP }}-access.log;
error_log /var/log/nginx/{{ .APP }}-error.log;
# set a custom header for requests
add_header X-Served-By www-ec2-01;
location / {
proxy_pass http://{{ .APP }};
proxy_http_version 1.1;
proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection "upgrade";
proxy_set_header Host $http_host;
proxy_set_header X-Forwarded-Proto $http_x_forwarded_proto;
proxy_set_header X-Forwarded-For $http_x_forwarded_for;
proxy_set_header X-Forwarded-Port $http_x_forwarded_port;
proxy_set_header X-Request-Start $msec;
}
include {{ .DOKKU_ROOT }}/{{ .APP }}/nginx.conf.d/*.conf;
upstream {{ .APP }} {
{{ range .DOKKU_APP_LISTENERS | split " " }}
server {{ . }};
{{ end }}
}
}
```
Only use this option if:

136
docs/nginx.md
View File

@@ -3,70 +3,74 @@
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
```
nginx:access-logs <app> [-t] Show the nginx access logs for an application (-t follows)
nginx:build-config <app> (Re)builds nginx config for given app
nginx:disable <app> Disable nginx for an application (forces container binding to external interface)
nginx:enable <app> Enable nginx for an application
nginx:error-logs <app> [-t] Show the nginx error logs for an application (-t follows)
nginx:access-logs <app> [-t] Show the nginx access logs for an application (-t follows)
nginx:build-config <app> (Re)builds nginx config for given app
nginx:error-logs <app> [-t] Show the nginx error logs for an application (-t follows)
```
## Customizing the nginx configuration
> New as of 0.3.10.
Dokku uses a templating library by the name of [sigil](https://github.com/gliderlabs/sigil) to generate nginx configuration for each app. If you'd like to provide a custom template for your application, there are a couple options:
Dokku currently templates out an nginx configuration that is included in the `nginx-vhosts` plugin. If you'd like to provide a custom template for your application, there are a few options:
- Copy the existing pertinent (ssl or non-ssl) template found (by default) in `/var/lib/dokku/plugins/available/nginx-vhosts/templates`, place it either in `/home/dokku/APP` or check it into the root of your app repo, and name it one of the following:
- `nginx.conf.template` (since 0.3.10)
- `nginx.conf.ssl_terminated.template` (since 0.4.0)
- `nginx.ssl.conf.template` (since 0.4.2)
> If placed on the dokku server, the template file **must** be owned by user and group `dokku:dokku`.
For instance - assuming defaults - to customize the nginx template in use for the `myapp` application, create the file `nginx.conf.template` in your repo or on disk with the with the following contents:
- Copy the following example template to a file named `nginx.conf.sigil` and either:
- check it into the root of your app repo
- `ADD` it to your dockerfile `WORKDIR`
### Example Custom Template
```
server {
listen [::]:80;
listen 80;
server_name $NOSSL_SERVER_NAME;
access_log /var/log/nginx/${APP}-access.log;
error_log /var/log/nginx/${APP}-error.log;
listen [::]:{{ .NGINX_PORT }};
listen {{ .NGINX_PORT }};
server_name {{ .NOSSL_SERVER_NAME }};
access_log /var/log/nginx/{{ .APP }}-access.log;
error_log /var/log/nginx/{{ .APP }}-error.log;
# set a custom header for requests
add_header X-Served-By www-ec2-01;
location / {
proxy_pass http://$APP;
proxy_pass http://{{ .APP }};
proxy_http_version 1.1;
proxy_set_header Upgrade \$http_upgrade;
proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection "upgrade";
proxy_set_header Host \$http_host;
proxy_set_header X-Forwarded-Proto \$scheme;
proxy_set_header X-Forwarded-For \$remote_addr;
proxy_set_header X-Forwarded-Port \$server_port;
proxy_set_header X-Request-Start \$msec;
proxy_set_header Host $http_host;
proxy_set_header X-Forwarded-Proto $scheme;
proxy_set_header X-Forwarded-For $remote_addr;
proxy_set_header X-Forwarded-Port $server_port;
proxy_set_header X-Request-Start $msec;
}
include {{ .DOKKU_ROOT }}/{{ .APP }}/nginx.conf.d/*.conf;
upstream {{ .APP }} {
{{ range .DOKKU_APP_LISTENERS | split " " }}
server {{ . }};
{{ end }}
}
include $DOKKU_ROOT/$APP/nginx.conf.d/*.conf;
}
```
The above is a sample http configuration that adds an `X-Served-By` header to requests.
A few tips for custom nginx templates:
- Special characters - dollar signs, spaces inside of quotes, etc. - should be escaped with a single backslash or can cause deploy failures.
- Templated files will be validated via `nginx -t`.
- Application environment variables can be used within your nginx configuration.
After your changes a `dokku deploy myapp` will regenerate the `/home/dokku/myapp/nginx.conf` file which is then used.
### Available template variables
```
{{ .APP }} Application name
{{ .APP_SSL_PATH }} Path to SSL certificate and key
{{ .DOKKU_ROOT }} Global dokku root directory (ex: app dir would be `{{ .DOKKU_ROOT }}/{{ .APP }}`)
{{ .DOKKU_APP_LISTENERS }} List of IP:PORT pairs of app containers
{{ .NGINX_PORT }} Non-SSL nginx listener port (same as `DOKKU_NGINX_PORT` config var)
{{ .NGINX_SSL_PORT }} SSL nginx listener port (same as `DOKKU_NGINX_SSL_PORT` config var)
{{ .NOSSL_SERVER_NAME }} List of non-SSL VHOSTS
{{ .RAW_TCP_PORTS }} List of exposed tcp ports as defined by Dockerfile `EXPOSE` directive (**Dockerfile apps only**)
{{ .SSL_INUSE }} Boolean set when an app is SSL-enabled
{{ .SSL_SERVER_NAME }} List of SSL VHOSTS
```
### Customizing via configuration files included by the default templates
The default nginx.conf- templates will include everything from your apps `nginx.conf.d/` subdirectory in the main `server {}` block (see above):
The default nginx.conf template will include everything from your apps `nginx.conf.d/` subdirectory in the main `server {}` block (see above):
```
include $DOKKU_ROOT/$APP/nginx.conf.d/*.conf;
include {{ .DOKKU_ROOT }}/{{ .APP }}/nginx.conf.d/*.conf;
```
That means you can put additional configuration in separate files, for example to limit the uploaded body size to 50 megabytes, do
@@ -86,7 +90,7 @@ Applications typically have the following structure for their hostname:
scheme://subdomain.domain.tld
```
The `subdomain` is inferred from the pushed application name, while the `domain` is set during initial configuration in the `$DOKKU_ROOT/VHOST` file.
The `subdomain` is inferred from the pushed application name, while the `domain` is set during initial configuration in the `$DOKKU_ROOT/VHOST` file or via `dokku domains:set-global`.
You can optionally override this in a plugin by implementing the `nginx-hostname` plugin trigger. For example, you can reverse the subdomain with the following sample `nginx-hostname` plugin trigger:
@@ -104,30 +108,32 @@ If the `nginx-hostname` has no output, the normal hostname algorithm will be exe
You can also use the built-in `domains` plugin to handle:
### Disabling VHOSTS
If desired, it is possible to disable vhosts by setting the environment variable `NO_VHOST=1`:
```shell
dokku config:set myapp NO_VHOST=1
```
On subsequent deploys, the nginx virtualhost will be discarded. This is useful when deploying internal-facing services that should not be publicly routeable. As of 0.4.0, nginx will still be configured to proxy your app on some random high port. This allows internal services to maintain the same port between deployments. You may change this port by setting `DOKKU_NGINX_PORT` and/or `DOKKU_NGINX_SSL_PORT` (for services configured to use SSL.)
### Domains plugin
> New as of 0.3.10
```shell
domains:add <app> DOMAIN Add a custom domain to app
domains <app> List custom domains for app
domains:clear <app> Clear all custom domains for app
domains:remove <app> DOMAIN Remove a custom domain from app
domains:add <app> DOMAIN Add a domain to app
domains [<app>] List domains
domains:clear <app> Clear all domains for app
domains:disable <app> Disable VHOST support
domains:enable <app> Enable VHOST support
domains:remove <app> DOMAIN Remove a domain from app
domains:set-global <domain> Set global domain name
```
The domains plugin allows you to specify custom domains for applications. This plugin is aware of any ssl certificates that are imported via `nginx:import-ssl`. Be aware that setting `NO_VHOST` will override any custom domains.
### Disabling VHOSTS
Custom domains are also backed up via the built-in `backup` plugin
If desired, it is possible to disable vhosts with the domains plugin.
```shell
dokku domains:disable myapp
```
On subsequent deploys, the nginx virtualhost will be discarded. This is useful when deploying internal-facing services that should not be publicly routeable. As of 0.4.0, nginx will still be configured to proxy your app on some random high port. This allows internal services to maintain the same port between deployments. You may change this port by setting `DOKKU_NGINX_PORT` and/or `DOKKU_NGINX_SSL_PORT` (for services configured to use SSL.)
The domains plugin allows you to specify custom domains for applications. This plugin is aware of any ssl certificates that are imported via `certs:add`. Be aware that disabling domains (with `domains:disable`) will override any custom domains.
```shell
# where `myapp` is the name of your app
@@ -145,26 +151,6 @@ dokku domains:clear myapp
dokku domains:remove myapp example.com
```
## Container network interface binding
> New as of 0.3.13
The deployed docker container running your app's web process will bind to either the internal docker network interface (i.e. `docker inspect --format '{{ .NetworkSettings.IPAddress }}' $CONTAINER_ID`) or an external interface (i.e. 0.0.0.0) depending on dokku's VHOST configuration. Dokku will attempt to bind to the internal docker network interface unless you specifically set NO_VHOST for the given app or your dokku installation is not setup to use VHOSTS (i.e. $DOKKU_ROOT/VHOST is missing or $DOKKU_ROOT/HOSTNAME is set to an IPv4 or IPv6 address)
```shell
# container bound to docker interface
root@dokku:~/dokku# docker ps
CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES
1b88d8aec3d1 dokku/node-js-app:latest "/bin/bash -c '/star About a minute ago Up About a minute goofy_albattani
root@dokku:~/dokku# docker inspect --format '{{ .NetworkSettings.IPAddress }}' goofy_albattani
172.17.0.6
# container bound to all interfaces (previous default)
root@dokku:/home/dokku# docker ps
CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES
d6499edb0edb dokku/node-js-app:latest "/bin/bash -c '/star About a minute ago Up About a minute 0.0.0.0:49153->5000/tcp nostalgic_tesla
```
## Default site

28
docs/proxy.md Normal file
View File

@@ -0,0 +1,28 @@
# Proxy plugin
As of dokku 0.5.0, the proxy functionality has been decoupled from the nginx-vhosts plugin into the proxy plugin. In the future this will allow other proxy software (HAproxy for example) to be used instead of nginx.
```
proxy:disable <app> Disable proxy for app
proxy:enable <app> Enable proxy for app
proxy:set <app> <proxy_type> NOT IMPLEMENTED YET!!
```
## Container network interface binding
By default, the deployed docker container running your app's web process will bind to the internal docker network interface (i.e. `docker inspect --format '{{ .NetworkSettings.IPAddress }}' $CONTAINER_ID`). This behavior can be modified per app by disabling the proxy (i.e. `dokku proxy:disable <app>`). In this case, the container will bind to an external interface (i.e. 0.0.0.0) and your app container will be directly accessible by other hosts on your network.
```shell
# container bound to docker interface
root@dokku:~/dokku# docker ps
CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES
1b88d8aec3d1 dokku/node-js-app:latest "/bin/bash -c '/star About a minute ago Up About a minute node-js-app.web.1
root@dokku:~/dokku# docker inspect --format '{{ .NetworkSettings.IPAddress }}' node-js-app.web.1
172.17.0.6
# container bound to all interfaces
root@dokku:/home/dokku# docker ps
CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES
d6499edb0edb dokku/node-js-app:latest "/bin/bash -c '/star About a minute ago Up About a minute 0.0.0.0:49153->5000/tcp node-js-app.web.1
```