HIPAA regulations require that protected health information is encrypted during transmission. Thus, it is important that your application is configured to use TLS (SSL). When TLS is enabled with Dokku, HTTP traffic will be automatically redirected to HTTPS. This is an industry-wide best practice for Web applications and services - notice sites like Google and GitHub no longer have HTTP-only pages.

Self-Signed Certificates

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

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

Configuring Free Certificates from Let's Encrypt

Let's Encrypt is a popular, trusted service, offering free certificates. New Dokku environments include a plugin for automatically provisioning certificates via the Let's Encrypt API. To confirm the plugin is enabled in your environment, run:

dokku letsencrypt:ls

If you receive an error, you can manually install the plugin:

sudo dokku plugin:install https://github.com/dokku/dokku-letsencrypt.git

Next, be sure you've defined any domains that will be used to route traffic to your applications. The Let's Encrypt plugin will query this list when creating the certificate.

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

To provision and install a certificate, do:

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

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 plugin:update letsencrypt
dokku letsencrypt:cron-job --add

Configuring Purchased Certificates

If you have already purchased a certificate from another certificate authority or don't want to use Let's Encrypt, here's how to associate your certificate with your application.

Reference: Creating a Third Party Certificate Request

On your local machine, 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 gd_bundle-g2-g1.crt > domain-bundle.crt
tar cvf ssl.tar domain-bundle.crt domain.key

Transfer ssl.tar to the server via scp. The file will end up in your home directory (~/) on the server:

scp ssl.tar deploy@server-id.healthcareblocks.com:~/

Now add it via dokku:

dokku certs:add my-app-name < ssl.tar

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

dokku certs:info my-app-name

If your certificate shows "SSL certificate is self signed" and you are using a real certificate, check whether your SSL vendor provides an intermediate bundle file - if so, merge it with your certificate as described above.

Stuck? We can help. Copy your key and cert files to the server and create a ticket letting us know where to find them and we'll do the rest.

High Availability Configurations

If your environment is using a cluster of Dokku instances, we recommend using the free AWS Certificate Manager service to attach a certificate to your load balancer and then use self-signed certificates in your Dokku instances (resulting in end-to-end encryption as required by AWS in HIPAA scenarios). Please create a help desk ticket for details.

Dokku Reference