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:
- Install mkcert
- 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:
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
androotCA.pem
from Slack or other internal system. - Move the
rootCA-key.pem
androotCA.pem
files into themkcert -CAROOT
directory on their machine. - Run
mkcert -install
on their machine.