Adding SSL (HTTPS) to Sourcegraph with a self-signed certificate

This is for external Sourcegraph instances that need a self-signed certificate because they don't yet have a certificate from a globally trusted Certificate Authority (CA). It includes how to get the self-signed certificate trusted by your browser.

NOTE: Using an IP address also works, including the browser being able to trust (validate) the SSL certificate.

Configuring NGINX with a self-signed certificate to support SSL requires:

1. Installing mkcert

While the OpenSSL CLI can can generate self-signed certificates, its API is challenging unless you're well versed in SSL.

A better alternative is mkcert, an abstraction over OpenSSL written by Filippo Valsorda, a cryptographer working at Google on the Go team.

NOTE: The following commands are to be run on the Docker host, not inside the Sourcegraph container.

To set up mkcert on the Sourcegraph instance:

  1. Install mkcert
  2. Create the root CA by running:
BASH
sudo CAROOT=~/.sourcegraph/config mkcert -install

2. Creating the self-signed certificate

Now that the root CA has been created, mkcert can issue a self-signed certificate (sourcegraph.crt) and key (sourcegraph.key).

BASH
sudo CAROOT=~/.sourcegraph/config mkcert \
  -cert-file ~/.sourcegraph/config/sourcegraph.crt \
  -key-file ~/.sourcegraph/config/sourcegraph.key \
  $HOSTNAME_OR_IP

Run sudo ls -la ~/.sourcegraph/config and you should see the CA and SSL certificates and keys.

3. Adding SSL support to NGINX

Edit the default ~/.sourcegraph/config/nginx.conf, so that port 7080 redirects to 7443 and 7443 is served with SSL. It should look like this:

NGINX
...
http {
    ...
    server {
        listen 7080;
        return 301 https://$host:7443$request_uri;
    }
 
    server {
        # Do not remove. The contents of sourcegraph_server.conf can change
        # between versions and may include improvements to the configuration.
        include nginx/sourcegraph_server.conf;
 
        listen 7443 ssl;
        server_name sourcegraph.example.com;  # change to your URL
        ssl_certificate         sourcegraph.crt;
        ssl_certificate_key     sourcegraph.key;
 
        location / {
            ...
        }
    }
}

4. Changing the Sourcegraph container to listen on port 443

NOTE: If the Sourcegraph container is still running, stop it before reading on.

Now that NGINX is listening on port 7443, we need to configure the Sourcegraph container to forward 443 to 7443 by adding --publish 443:7443 to the docker run command:

BASH
docker container run \
  --rm  \
  --publish 7080:7080 \
  --publish 443:7443 \
  \
  --volume ~/.sourcegraph/config:/etc/sourcegraph  \
  --volume ~/.sourcegraph/data:/var/opt/sourcegraph  \
  sourcegraph/server:5.6.2535

NOTE: We recommend removing --publish 7080:7080 as it's not needed and traffic sent to that port is un-encrypted.

Run the new Docker command, then validate by opening your browser at https://$HOSTNAME_OR_IP.

If running Sourcegraph locally, the certificate will be valid because mkcert added the root CA to the list trusted by your OS.

5. Getting the self-signed certificate to be trusted (valid) on external instances

To have the browser trust the certificate, the root CA on the Sourcegraph instance must be installed locally by:

1. Installing mkcert locally

2. Downloading rootCA-key.pem and rootCA.pem from ~/.sourcegraph/config/mkcert on the Sourcegraph instance to the location of mkcert -CAROOT on your local machine:

BASH
# Run locally: Ensure directory the root CA files will be downloaded to exists
mkdir -p "$(mkcert -CAROOT)"
BASH
# Run on Sourcegraph host: Ensure `scp` user can read (and therefore download) the root CA files
sudo chown $USER ~/.sourcegraph/config/root*
BASH
# Run locally: Download the files (change username and hostname)
scp user@example.com:~/.sourcegraph/config/root* "$(mkcert -CAROOT)"

3. Install the root CA by running:

BASH
mkcert -install

Open your browser again at https://$HOSTNAME_OR_IP and this time, your certificate should be valid.

Getting the self-signed cert trusted on other developer machines

This is largely the same as step 5, except easier. For other developer machines to trust the self-signed cert:

  • Install mkcert.
  • Download the rootCA-key.pem and rootCA.pem from Slack or other internal system.
  • Move the rootCA-key.pem and rootCA.pem files into the mkcert -CAROOT directory on their machine.
  • Run mkcert -install on their machine.

Next steps