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

Update documentation on ssl management

Browse Source 
Also move into subdirectory

[ci skip]
This commit is contained in:
Jose Diaz-Gonzalez
2015-09-03 23:31:18 -04:00
parent d37e64d3d6
commit db4e847e8d
5 changed files with 96 additions and 82 deletions
Download Patch File Download Diff File Expand all files Collapse all files

90
docs/deployment/ssl-configuration.md Normal file
View File

@@ -0,0 +1,90 @@
# SSL Configuration
> New as of 0.4.0
Dokku supports SSL/TLS certificate inspection and CSR/Self-signed certificate generation via the `certs` plugin. Note that whenever SSL/TLS support is enabled SPDY is also enabled.
```
certs:add <app> Add an ssl endpoint to an app. Imports a tarball from stdin; should contain server.crt and server.key
certs:generate <app> DOMAIN Generate a key and certificate signing request (and self-signed certificate)
certs:info <app> Show certificate information for an ssl endpoint.
certs:remove <app> Remove an SSL Endpoint from an app.
```
## Per-application certificate management
Dokku provides built-in support for managing SSL certificates on a per-application basis. SSL is managed via nginx outside of application containers, and as such can be updated on-the-fly without rebuilding containers.
### Certificate setting
The `certs:add` command can be used to push a `tar` containing a certificate `.crt` and `.key` file to a single application. The command should correctly handle cases where the `.crt` and `.key` are not named properly or are nested in a subdirectory of said `tar` file. You can import it as follows:
```shell
tar cvf cert-key.tar server.crt server.key
# replace APP with your app name
dokku certs:add < cert-key.tar
```
You will need to repeat the steps above for each domain used to serve your app. You can't simply create a single tar with all key/cert files in it (see this [issue](https://github.com/progrium/dokku/issues/1195) for more details).
### Certificate generation
> Note: Using this method will create a self-signed certificate, which is only recommended for development or staging use, not production environments.
The `certs:generate` command will walk you through the correct `openssl` commands to create a key, csr and a self-signed cert for a given app/domain. We automatically put the self-signed cert in place as well as add the specified domain to the application configuration. If you decide to obtain a CA signed certficate, simply place it in `$DOKKU_ROOT/$APP/tls/server.crt` and run `dokku nginx:build-config $APP`.
### Certificate information
The `certs:info` command will simply inspect the install SSL cert and print out details. NOTE: The server-wide certificate will be inspect if installed and no app-specific certificate exists.
```
root@dokku:~/dokku# dokku certs:info node-js-app
-----> Fetching SSL Endpoint info for node-js-app...
-----> Certificate details:
=====> Common Name(s):
=====> test.dokku.me
=====> Expires At: Aug 24 23:32:59 2016 GMT
=====> Issuer: C=US, ST=California, L=San Francisco, O=dokku.me, CN=test.dokku.me
=====> Starts At: Aug 25 23:32:59 2015 GMT
=====> Subject: C=US; ST=California; L=San Francisco; O=dokku.me; CN=test.dokku.me
=====> SSL certificate is self signed.
```
### `certs:remove` command
The `certs:remove` command only works on app-specific certificates. It will `rm` the app-specific tls directory, rebuild the nginx configuration, and reload nginx.
## Global Certification
Global certificate management is a manual process. To enable TLS connections for all your applications at once you will need a wildcard TLS certificate.
To enable TLS across all apps, you can run the following commands:
```shell
mkdir -p /home/dokku/tls
cp server.crt /home/dokku/tls/server.crt
cp server.key /home/dokku/tls/server.key
```
Next, you will want to enable the certificates by editing `/etc/nginx/conf.d/dokku.conf` and uncommenting these two lines (remove the `#`):
```
ssl_certificate /home/dokku/tls/server.crt;
ssl_certificate_key /home/dokku/tls/server.key;
```
The settings will take affect at the next deploy. If you would like to propagate the change to all apps immediately, you can also run the following command:
```shell
dokku ps:restartall
```
Once TLS is enabled, the application will be accessible by `https://` (redirection from `http://` is applied as well).
> Note: TLS will not be enabled unless the application's VHOST matches the certificate's name. (i.e. if you have a cert for `*.example.com` TLS won't be enabled for `something.example.org` or `example.net`)
## HSTS Header
The [HSTS header](https://en.wikipedia.org/wiki/HTTP_Strict_Transport_Security) is an HTTP header that can inform browsers that all requests to a given site should be made via HTTPS. dokku does not, by default, enable this header. It is thus left up to you, the user, to enable it for your site.
Beware that if you enable the header and a subsequent deploy of your application results in an HTTP deploy (for whatever reason), the way the header works means that a browser will not attempt to request the HTTP version of your site if the HTTPS version fails.

51
docs/nginx.md
View File

@@ -2,54 +2,11 @@
Dokku uses nginx as it's 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
## TLS/SPDY support
## SSL Configuration
Dokku provides easy TLS/SPDY support out of the box. This can be done app-by-app or for all subdomains at once. Note that whenever TLS support is enabled SPDY is also enabled.
> New as of 0.4.0.
### Per App
To enable TLS connections to to one of your applications, do the following:
* Create a key file and a cert file.
* You can find detailed steps for generating a self-signed certificate at https://devcenter.heroku.com/articles/ssl-certificate-self
* If you are not paranoid and need it just for a DEV or STAGING app, you can use http://www.selfsignedcertificate.com/ to generate your 2 files more easily.
* Rename your files to server.key and server.crt
* tar these 2 files together, *without* subdirectories. Example: tar cvf cert-key.tar server.crt server.key
* Install the pair for your app, like this: ssh dokku@ip-of-your-dokku-server certs:add < cert-key.tar
You will need to repeat the steps above for each domain used to serve your app. You can't simply create a single tar with all key/cert files in it (see https://github.com/progrium/dokku/issues/1195).
### All Subdomains
To enable TLS connections for all your applications at once you will need a wildcard TLS certificate.
To enable TLS across all apps, copy or symlink the `.crt` and `.key` files into the `/home/dokku/tls` folder (create this folder if it doesn't exist) as `server.crt` and `server.key` respectively. Then, enable the certificates by editing `/etc/nginx/conf.d/dokku.conf` and uncommenting these two lines (remove the #):
```
ssl_certificate /home/dokku/tls/server.crt;
ssl_certificate_key /home/dokku/tls/server.key;
```
The nginx configuration will need to be reloaded in order for the updated TLS configuration to be applied. This can be done either via the init system or by re-deploying the application. Once TLS is enabled, the application will be accessible by `https://` (redirection from `http://` is applied as well).
**Note**: TLS will not be enabled unless the application's VHOST matches the certificate's name. (i.e. if you have a cert for *.example.com TLS won't be enabled for something.example.org or example.net)
### HSTS Header
The [HSTS header](https://en.wikipedia.org/wiki/HTTP_Strict_Transport_Security) is an HTTP header that can inform browsers that all requests to a given site should be made via HTTPS. dokku does not, by default, enable this header. It is thus left up to you, the user, to enable it for your site.
Beware that if you enable the header and a subsequent deploy of your application results in an HTTP deploy (for whatever reason), the way the header works means that a browser will not attempt to request the HTTP version of your site if the HTTPS version fails.
### Importing ssl certificates
You can import ssl certificates via tarball using the following command:
``` bash
dokku certs:add myapp < archive-of-certs.tar
```
This archive should is expanded via `tar xvf`. It should contain `server.crt` and `server.key`.
[See the full documentation](http://progrium.viewdocs.io/dokku/deployment/ssl-configuration).
## Customizing the nginx configuration
@@ -152,7 +109,7 @@ On subsequent deploys, the nginx virtualhost will be discarded. This is useful w
> New as of 0.3.10
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 setting `NO_VHOST` will override any custom domains.
The domains plugin allows you to specify custom domains for applications. This plugin is aware of any ssl certificates that are imported via the `certs` plugin. Be aware that setting `NO_VHOST` will override any custom domains.
Custom domains are also backed up via the built-in `backup` plugin

34
docs/ssl-certificate-management.md
View File

@@ -1,34 +0,0 @@
# SSL Certificates
Dokku supports SSL/TLS certificate inspection and CSR/Self-signed certificate generation via the `certs` plugin
```
certs:generate <app> DOMAIN Generate a key and certificate signing request (and self-signed certificate)
certs:info <app> Show certificate information for an ssl endpoint.
certs:remove <app> Remove an SSL Endpoint from an app.
```
## Certificate generation
The `certs:generate` command will walk you through the correct `openssl` commands to create a key, csr and a self-signed cert for a given app/domain. We automatically put the self-signed cert in place as well as add the specified domain to the application configuration. If you decide to obtain a CA signed certficate, simply place it in `$DOKKU_ROOT/$APP/tls/server.crt` and run `dokku nginx:build-config $APP`.
### Certificate information
The `certs:info` command will simply inspect the install SSL cert and print out details. NOTE: The server-wide certificate will be inspect if installed and no app-specific certificate exists.
```
root@dokku:~/dokku# dokku certs:info node-js-app
-----> Fetching SSL Endpoint info for node-js-app...
-----> Certificate details:
=====> Common Name(s):
=====> test.dokku.me
=====> Expires At: Aug 24 23:32:59 2016 GMT
=====> Issuer: C=US, ST=California, L=San Francisco, O=dokku.me, CN=test.dokku.me
=====> Starts At: Aug 25 23:32:59 2015 GMT
=====> Subject: C=US; ST=California; L=San Francisco; O=dokku.me; CN=test.dokku.me
=====> SSL certificate is self signed.
```
### `certs:remove` command
The `certs:remove` command only works on app-specific certificates. It will `rm` the app-specific tls directory, rebuild the nginx configuration, and reload nginx.

2
docs/template.html
View File

@@ -64,7 +64,7 @@
<a href="http://progrium.viewdocs.io/dokku/process-management" class="list-group-item">Process management</a>
<a href="http://progrium.viewdocs.io/dokku/dns" class="list-group-item">DNS Configuration</a>
<a href="http://progrium.viewdocs.io/dokku/nginx" class="list-group-item">Nginx Configuration</a>
<a href="http://progrium.viewdocs.io/dokku/ssl-certificate-management" class="list-group-item">SSL Configuration</a>
<a href="http://progrium.viewdocs.io/dokku/deployment/ssl-configuration" class="list-group-item">SSL Configuration</a>
<a href="http://progrium.viewdocs.io/dokku/remote-commands" class="list-group-item">Running Remote commands</a>
<a href="http://progrium.viewdocs.io/dokku/docker-options" class="list-group-item">Container Options</a>
<a href="http://progrium.viewdocs.io/dokku/dokku-events-logs" class="list-group-item">Dokku Event Logs</a>

1
plugins/certs/commands
View File

@@ -41,6 +41,7 @@ case "$1" in
rm -rf $TEMP_DIR
dokku nginx:build-config $APP
;;
certs:generate)
[[ -z $2 ]] && echo "Please specify an app to run the command on" && exit 1
verify_app_name "$2"