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

Merge pull request #2089 from dokku/2086-ssl-certs

Browse Source 
Update how ssl and multiple domains interact
This commit is contained in:
Jose Diaz-Gonzalez
2016-04-09 15:15:22 -04:00
parent 4945bd79ca db94fcb6b4
commit f29f4294c7
6 changed files with 124 additions and 95 deletions
Download Patch File Download Diff File Expand all files Collapse all files

98
docs/deployment/domain-configuration.md Normal file
View File

@@ -0,0 +1,98 @@
# Domain Configuration
> New as of 0.3.10
```shell
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
```
## Customizing hostnames
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.tld` is set during initial configuration and stored in the `$DOKKU_ROOT/VHOST` file. It can then be modified with `dokku domains:set-global`. This value is used as a default TLD for all applications on a host.
If a FQDN such as `other.tld` is used as the application name, the default `$DOKKU_ROOT/VHOST` will be ignored and the resulting vhost URL for that application will be `other.tld`. The exception to this rule being that if the FQDN has the same ending as the default vhost (such as `subdomain.domain.tld`), then the entire FQDN will be treated as a subdomain. The application will therefore be deployed at `subdomain.domain.tld.domain.tld`.
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:
```shell
#!/usr/bin/env bash
set -eo pipefail; [[ $DOKKU_TRACE ]] && set -x
APP="$1"; SUBDOMAIN="$2"; VHOST="$3"
NEW_SUBDOMAIN=`echo $SUBDOMAIN | rev`
echo "$NEW_SUBDOMAIN.$VHOST"
```
If the `nginx-hostname` has no output, the normal hostname algorithm will be executed.
## Disabling VHOSTS
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
# add a domain to an app
dokku domains:add myapp example.com
# list custom domains for app
dokku domains myapp
# clear all custom domains for app
dokku domains:clear myapp
# remove a custom domain from app
dokku domains:remove myapp example.com
```
## Default site
By default, dokku will route any received request with an unknown HOST header value to the lexicographically first site in the nginx config stack. If this is not the desired behavior, you may want to add the following configuration to the global nginx configuration. This will catch all unknown HOST header values and return a `410 Gone` response. You can replace the `return 410;` with `return 444;` which will cause nginx to not respond to requests that do not match known domains (connection refused).
```
server {
listen 80 default_server;
listen [::]:80 default_server;
server_name _;
return 410;
log_not_found off;
}
```
You may also wish to use a separate vhost in your `/etc/nginx/sites-enabled` directory. To do so, create the vhost in that directory as `/etc/nginx/sites-enabled/00-default.conf`. You will also need to change two lines in the main `nginx.conf`:
```
# Swap both conf.d include line and the sites-enabled include line. From:
include /etc/nginx/conf.d/*.conf;
include /etc/nginx/sites-enabled/*;
# to the following
include /etc/nginx/sites-enabled/*;
include /etc/nginx/conf.d/*.conf;
```
Alternatively, you may push an app to your dokku host with a name like "00-default". As long as it lists first in `ls /home/dokku/*/nginx.conf | head`, it will be used as the default nginx vhost.

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

@@ -35,6 +35,12 @@ dokku certs:add <app> < cert-key.tar
cat yourdomain_com.crt yourdomain_com.ca-bundle > server.crt
```
#### SSL and Multiple Domains
When an SSL certificate is associated to an application, the certificate will be associated with *all* domains currently associated with said application. Your certificate _should_ be associated with all of those domains, otherwise accessing the application will result in SSL errors. If you wish to remove one of the domains from the application, refer to the [domain configuration documentation](/dokku/deployment/domain-configuration/).
Note that with the default nginx template, requests will be redirected to the `https` version of the domain. If this is not the desired state of request resolution, you may customize the nginx template in use. For more details, see the [nginx documentation](/dokku/nginx/).
### Certificate generation
> Note: Using this method will create a self-signed certificate, which is only recommended for development or staging use, not production environments.

102
docs/nginx.md
View File

@@ -131,107 +131,21 @@ chown dokku:dokku /home/dokku/myapp/nginx.conf.d/upload.conf
service nginx reload
```
## Domains plugin
See the [domain-configuration documentation](/dokku/deployment/domain-configuration/).
## Customizing hostnames
Applications typically have the following structure for their hostname:
See the [customizing hostnames documentation](/dokku/deployment/domain-configuration/#customizing-hostnames).
```
scheme://subdomain.domain.tld
```
The `subdomain` is inferred from the pushed application name, while the `domain.tld` is set during initial configuration and stored in the `$DOKKU_ROOT/VHOST` file. It can then be modified with `dokku domains:set-global`. This value is used as a default TLD for all applications on a host.
If a FQDN such as `other.tld` is used as the application name, the default `$DOKKU_ROOT/VHOST` will be ignored and the resulting vhost URL for that application will be `other.tld`. The exception to this rule being that if the FQDN has the same ending as the default vhost (such as `subdomain.domain.tld`), then the entire FQDN will be treated as a subdomain. The application will therefore be deployed at `subdomain.domain.tld.domain.tld`.
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:
```shell
#!/usr/bin/env bash
set -eo pipefail; [[ $DOKKU_TRACE ]] && set -x
APP="$1"; SUBDOMAIN="$2"; VHOST="$3"
NEW_SUBDOMAIN=`echo $SUBDOMAIN | rev`
echo "$NEW_SUBDOMAIN.$VHOST"
```
If the `nginx-hostname` has no output, the normal hostname algorithm will be executed.
You can also use the built-in `domains` plugin to handle:
### Domains plugin
> New as of 0.3.10
```shell
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
```
### Disabling VHOSTS
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
# add a domain to an app
dokku domains:add myapp example.com
# list custom domains for app
dokku domains myapp
# clear all custom domains for app
dokku domains:clear myapp
# remove a custom domain from app
dokku domains:remove myapp example.com
```
## Disabling VHOSTS
See the [disabling vhosts documentation](/dokku/deployment/domain-configuration/#disabling-vhosts).
## Default site
By default, dokku will route any received request with an unknown HOST header value to the lexicographically first site in the nginx config stack. If this is not the desired behavior, you may want to add the following configuration to the global nginx configuration. This will catch all unknown HOST header values and return a `410 Gone` response. You can replace the `return 410;` with `return 444;` which will cause nginx to not respond to requests that do not match known domains (connection refused).
```
server {
listen 80 default_server;
listen [::]:80 default_server;
server_name _;
return 410;
log_not_found off;
}
```
You may also wish to use a separate vhost in your `/etc/nginx/sites-enabled` directory. To do so, create the vhost in that directory as `/etc/nginx/sites-enabled/00-default.conf`. You will also need to change two lines in the main `nginx.conf`:
```
# Swap both conf.d include line and the sites-enabled include line. From:
include /etc/nginx/conf.d/*.conf;
include /etc/nginx/sites-enabled/*;
# to the following
include /etc/nginx/sites-enabled/*;
include /etc/nginx/conf.d/*.conf;
```
Alternatively, you may push an app to your dokku host with a name like "00-default". As long as it lists first in `ls /home/dokku/*/nginx.conf | head`, it will be used as the default nginx vhost.
See the [default site documentation](/dokku/deployment/domain-configuration/#default-site).
## Running behind a load balancer

3
docs/template.html
View File

@@ -107,7 +107,8 @@
<a href="#" class="list-group-item disabled">Configuration</a>
<a href="/dokku/configuration-management/" class="list-group-item">Environment Variables</a>
<a href="/dokku/dns" class="list-group-item">DNS Configuration</a>
<a href="/dokku/dns/" class="list-group-item">DNS Configuration</a>
<a href="/dokku/deployment/domains/" class="list-group-item">Domain Configuration</a>
<a href="/dokku/nginx/" class="list-group-item">Nginx Configuration</a>
<a href="/dokku/deployment/ssl-configuration/" class="list-group-item">SSL Configuration</a>
<a href="/dokku/dokku-events-logs/" class="list-group-item">Dokku Event Logs</a>

1
plugins/nginx-vhosts/templates/ssl.server.config
View File

@@ -2,6 +2,7 @@ server {
listen [::]:{{ .NGINX_SSL_PORT }} ssl spdy;
listen {{ .NGINX_SSL_PORT }} ssl spdy;
{{ if .SSL_SERVER_NAME }}server_name {{ .SSL_SERVER_NAME }}; {{ end }}
{{ if .NOSSL_SERVER_NAME }}server_name {{ .NOSSL_SERVER_NAME }}; {{ end }}
{{ include "log.config" . }}
ssl_certificate {{ .APP_SSL_PATH }}/server.crt;
ssl_certificate_key {{ .APP_SSL_PATH }}/server.key;

9
tests/unit/40_nginx-vhosts_2.bats
View File

@@ -41,6 +41,15 @@ assert_error_log() {
assert_error_log ${TEST_APP}
}
@test "(nginx-vhosts) nginx:build-config (with SSL & unrelated domain)" {
setup_test_tls
add_domain "node-js-app.dokku.me"
add_domain "test.dokku.me"
deploy_app
assert_ssl_domain "node-js-app.dokku.me"
assert_http_redirect "http://test.dokku.me" "https://test.dokku.me:443/"
}
@test "(nginx-vhosts) nginx:build-config (wildcard SSL)" {
setup_test_tls wildcard
add_domain "wildcard1.dokku.me"