Skip to content

Latest commit

 

History

History
59 lines (42 loc) · 3.37 KB

setup.md

File metadata and controls

59 lines (42 loc) · 3.37 KB
Raw

Configuring SSL for Hotline

Setting up SSL certificates for Hotline is pretty straightforward, but requires some manual changes to be made.

1. Start up Hotline

To successfully generate certificates, Hotline must be running and responding properly on your web app domain and callback domain. The below steps assume you are using the provided Docker/Docker Compose configurations. If you are using a more custom configuration, you'll need to adapt these steps to your deployment.

2. Issue certificates

The provided SSL certificate generation script uses Let's Encrypt and Certbot to handle certificate issuance.

$ cd ssl
$ ./gen_certs.sh -a hotlinewebapp.xyz -c hotlinecallback.net

This script will generate a certificate using a HTTP-01 challenge for your app domain, and a wildcard certificate using a DNS-01 challenge for your callback domain.

The app challenge works by sharing a folder between the NGINX proxy and Certbot, where the challenge verification data is stored and statically served by NGINX.

The callback challenge works by sharing a folder between the DNS callback service and Certbot, where the TXT records used for challenge verification are stored. Please make sure that server.callback.dns.acme_challenge_path is accurate (if using the provided setup, it should be "/acme/response").

3. Configure NGINX to use the certificates

Now that the certs are provisioned, they are stored in ssl/app_cert and ssl/callback_cert accordingly. Additionally, the ssl/letsencrypt directory that was generated by Certbot contains additional files that may be useful for more custom Hotline deployments.

Edit your nginx/nginx.conf file and make the following changes:

  • In your webapp server block, uncomment the following lines. This tells NGINX to start listening on port 443 for SSL connections, and sets the path to the certificate and the private key.
    #listen 443 ssl;
    #ssl_certificate /app_cert/fullchain.pem;
    #ssl_certificate_key /app_cert/privkey.pem;
  • In your callback server block, uncomment the same lines:
    #listen 443 ssl;
    #ssl_certificate /callback_cert/fullchain.pem;
    #ssl_certificate_key /callback_cert/privkey.pem;
  • Optionally, if you want HTTP connections to redirect to HTTPS for the web app/API, uncomment these lines:
    #if ($scheme = http) {
    #    return 301 https://$host$request_uri;
    #}

Please note that if you uncomment any of these blocks before certificates are successfully issues, Certbot won't be able to properly generate certificates.

Also, if you setup SSL redirection, you need to update the client.server_url in hotline.yml to change the scheme to https:// instead of http://.

Notes

There are a couple caveats to be aware of for the HTTP callback service now that SSL is enabled:

  • The Hotline CLI client will still show http:// as the scheme for the sample cURL command. You can change this to HTTPS for your own usage now that certs are enabled.
  • Due to how SSL certificates work, you can't use HTTPS for additional subdomains off of your callback domain.
    • For example, you can do https://evt8cy42vlk89knedlu7.hotlinecallback.net, but you can't do https://otherthing.evt8cy42vlk89knedlu7.hotlinecallback.net. For that, you'll have to revert back to HTTP.
    • This is why there is no HTTP->HTTPS redirect provided, as it will cause any additional subdomains to fail SSL validation.