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.

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.

To set up mkcert on the Sourcegraph instance:

  1. Install mkcert
  2. Create the root CA by running:
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).

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:

...
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

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

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

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:

# Run locally: Ensure directory the root CA files will be downloaded to exists
mkdir -p "$(mkcert -CAROOT)"

# Run on Sourcegraph host: Ensure `scp` user can read (and therefore download) the root CA files
sudo chown $USER ~/.sourcegraph/config/root*

# Run locally: Download the files (change username and hostname)
scp [email protected]:~/.sourcegraph/config/root* "$(mkcert -CAROOT)"

3. Install the root CA by running:

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