Managing SSL Certificates

HIPAA regulations require that protected health information is encrypted during transmission. Thus, it is important that your application is configured to use SSL (TLS). When SSL is enabled with Dokku, HTTP traffic will be automatically redirected to HTTPS. This is an industry-wide best practice for Web applications.

Self-Signed Certificates

For testing purposes, you can create a self-signed SSL certificate:

dokku certs:generate my-app \
  my-app.server-id.healthcareblocks.com

Configuring Free Certificates from Let's Encrypt

Let's Encrypt is a popular, trusted service, offering free certificates. Dokku environments include a plugin for automatically provisioning certificates via the Let's Encrypt API.

First, ensure you've defined any domains that will be used to route traffic to your applications. Let's Encrypt will query this list using public DNS records before it issues the certificate.

dokku domains:add my-app \
  www.mydomain.com api.mydomain.com etc...

To provision and install a certificate, do:

dokku config:set --no-restart my-app \
  DOKKU_LETSENCRYPT_EMAIL=me@mydomain.com

dokku letsencrypt my-app

The email should be an address associated with your domain.

Let's Encrypt certificates automatically expire every 90 days. You'll need to define a cron job to have the cert automatically renewed by Dokku.

dokku letsencrypt:cron-job --add

Configuring Purchased Certificates

If you have already purchased a certificate from another certificate authority, here's how to associate your certificate with your application.

Combine your certificate and private key into a file named ssl.tar:

tar cvf ssl.tar domain.crt domain.key

Note: if your cert included a "bundle" file, combine it first with the cert:

cat domain.crt bundle.crt > domain-bundle.crt
tar cvf ssl.tar domain-bundle.crt domain.key

Now add it via Dokku:

dokku certs:add my-app < ssl.tar

To verify an app's certificate, including expiration date:

dokku certs:info my-app

High Availability Configurations

If your environment consists of one or more Dokku servers behind a load balancer, Healthcare Blocks will coordinate with you on provisioning a free SSL certificate using the AWS Certificate Manager service.

AWS requires end-to-end encryption in HIPAA-regulated environments. Therefore, your Dokku servers will continue to use their own SSL certificates. However, AWS load balancers do not validate certificates used on internal endpoints, therefore, these can be generated using the "self-signed" method shown at the top of this page.

Dokku Reference