Local SSL Certificates for HTTPS

When working locally you will be required to work on an HTTPS version of your site, similar to how the site is hosted in production. The standard Lapis containers support hosting an HTTPS version of the site, however, we will need to generate some SSL certificates and mount them into the container, along with the configuration file for it to work.

Installation of mkcert

A problem with generating self signed certificates is that browsers will warn you that you might be connecting to an untrusted site. To get around this issue, we use a tool call mkcert. This tool can generate a local certificate authority (CA) and then create self signed certificates that will be trusted by your browsers.

Linux

Dependencies

You will need to make sure the you have the required dependencies before installing the mkcert tool

sudo apt install libnss3-tools

Download latest mkcert version

Visit the official mkcert releases page and download the latest version (currently 1.4.4). We will need to rename the file, make it executable, and then copy it into a folder in your $PATH (will we use /usr/local/bin).

cd ~/Downloads
wget https://github.com/FiloSottile/mkcert/releases/download/v1.4.4/mkcert-v1.4.4-linux-amd64 -O mkcert
chmod +x mkcert
sudo mv mkcert /usr/local/bin

Windows

Install Chocolatey

There are several ways of installing mkcert but the easiest is to use Chocolatey. Run Powershell as an Administrator and execute the following

Set-ExecutionPolicy Bypass -Scope Process -Force; [System.Net.ServicePointManager]::SecurityProtocol = [System.Net.ServicePointManager]::SecurityProtocol -bor 3072; iex ((New-Object System.Net.WebClient).DownloadString('https://community.chocolatey.org/install.ps1'))

Install mkcert

Use Chocolatey to download and install mkcert

choco install mkcert

Installation of certificate authority

Once mkcert has been downloaded into the correct location we need to install the certificate authority that will be trusted by the browsers and can be used to generate the self signed certificates. You can run the following command for both Windows and Linux

mkcert -install

Creating self signed certificates

Now we have the CA installed we can create the self signed certificates that will be used by Lapis to host the site. These certificates will be wildcard certificates that will work with any subdomain that you want to run locally.

Linux

cd ~/Workspace/lapis
mkcert \
  -cert-file self.crt \
  -key-file self.key \
  "*.<first>.<last>.local.internihr.ninja"

Windows

Run Powershell as an Administrator and then create the self-signed certificates. After executing the command below, use File Explorer to copy the files self.crt and self.key and paste it into the lapis directory. Restart your machine for the changes to take effect

mkcert -cert-file self.crt -key-file self.key "*.<first>.<last>.local.internihr.ninja"

Updating Lapis configuration (if not first time set up)

For developers with an existing non-HTTPS setup, it is necessary to make some changes to your local docker compose override. If you are following the quick start guide, this step is not needed.

The local HTTPS site was previously not included by default. To enable it you need to make some changes. Ensure the following options are present in your docker-compose.override.yml file (along with the existing settings):

services:
  local:
    ports:
      - '443:443'
    volumes:
      - ./self.crt:/etc/ssl/certs/self.crt:ro
      - ./self.key:/etc/ssl/certs/self.key:ro
      - ./docker/nginx/conf/local-https.conf:/etc/nginx/conf.d/https.conf:ro

With these changes you should now be able to access your local site via HTTPS.