SiteEncrypt

This project aims to provide integrated certification via Let’s encrypt for sites implemented in Elixir.

Integrated certification means that you don’t need to run any other OS process in background. Start your site for the first time, and the system will obtain the certificate, and periodically renew it before it expires.

The target projects are small-to-medium Elixir based sites which don’t sit behind reverse proxies such as nginx.

Status

• The library is tested in a simple production, where it has been constantly running since mid 2018.
• Native Elixir client is very new, and not considered stable. If you prefer reliable behaviour, use the Certbot client. This will require installing Certbot >= 0.31
• The API is not stable. Expect breaking changes in the future.

Testing in production

In general, the configuration above should work out of the box in production, as long as the domain is correctly setup, and ports properly forwarded, so the HTTP site is externally available at port 80.

If you want a more manual first deploy test, here’s how you can do it:

1. Explicitly set mode: :manual in certification/0. This means that the site won’t automatically certify itself. However, during the first boot it will generate a self-signed certificate.

2. Deploy the site and verify that it’s externally reachable via HTTP on port 80.

3. Start a remote iex shell session to the running system.

4. Perform a trial certification through the staging Let’s Encrypt CA:

   iex> SiteEncrypt.dry_certify(
          MySystemWeb.Endpoint,
          directory_url: "https://acme-staging-v02.api.letsencrypt.org/directory"
        )
   

Keep in mind that this can be only invoked in the remote iex shell session inside the running system.

If the certification succeeds, the function will return the key and the certificate. These files won’t be stored on disk, and they won’t be used by the endpoint.

1. If the trial certification succeeded, you can proceed to start the real certification as follows:

   iex> SiteEncrypt.force_certify(MySystemWeb.Endpoint)
   

Unlike the trial certification, this function will go to the CA as configured by the certification/0 callback in the endpoint. The key and the certificate files will be stored on the disk, and the site will immediately used them. Therefore, if this function succeeds, you can visit your site via HTTPS.

1. If all went well, remove the :mode setting from the certification/0 callback and redeploy your system.

Note: be careful not to invoke these functions too frequently, because you might trip some rate limit on Let’s Encrypt. See here for more details.