diff --git a/docs/deployment/ssl-configuration.md b/docs/deployment/ssl-configuration.md new file mode 100644 index 000000000..7bfce70d2 --- /dev/null +++ b/docs/deployment/ssl-configuration.md @@ -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 Add an ssl endpoint to an app. Imports a tarball from stdin; should contain server.crt and server.key +certs:generate DOMAIN Generate a key and certificate signing request (and self-signed certificate) +certs:info Show certificate information for an ssl endpoint. +certs:remove 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. diff --git a/docs/nginx.md b/docs/nginx.md index 832b256d8..e09c1ce65 100644 --- a/docs/nginx.md +++ b/docs/nginx.md @@ -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 diff --git a/docs/ssl-certificate-management.md b/docs/ssl-certificate-management.md deleted file mode 100644 index 56c5de8a9..000000000 --- a/docs/ssl-certificate-management.md +++ /dev/null @@ -1,34 +0,0 @@ -# SSL Certificates - -Dokku supports SSL/TLS certificate inspection and CSR/Self-signed certificate generation via the `certs` plugin - -``` -certs:generate DOMAIN Generate a key and certificate signing request (and self-signed certificate) -certs:info Show certificate information for an ssl endpoint. -certs:remove 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. diff --git a/docs/template.html b/docs/template.html index 30ff58c67..fa646570e 100644 --- a/docs/template.html +++ b/docs/template.html @@ -64,7 +64,7 @@ Process management DNS Configuration Nginx Configuration - SSL Configuration + SSL Configuration Running Remote commands Container Options Dokku Event Logs diff --git a/plugins/certs/commands b/plugins/certs/commands index e667e8c81..c42468d7a 100755 --- a/plugins/certs/commands +++ b/plugins/certs/commands @@ -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"