Sourcegraph HTTP and HTTPS/SSL configuration
Overview:
- Single Docker image (
sourcegraph/server
): NGINX - Sourcegraph Cluster (Kubernetes): NGINX
- Docker Compose: Caddy 2
- Other Sourcegraph clusters (e.g. pure-docker)
Sourcegraph single Docker image and Sourcegraph Cluster (Kubernetes): NGINX
Sourcegraph's single Docker image and Kubernetes deployments use NGINX as a reverse proxy for the Sourcegraph front-end server, meaning NGINX proxies external HTTP (and HTTPS) requests to the Sourcegraph front-end.
Note: Non-sighted users can view a text-representation of this diagram.
Sourcegraph single instance (Docker)
The first time Sourcegraph is run, it will create an nginx.conf
file at:
~/.sourcegraph/config/nginx.conf
on the Docker/Sourcegraph host (presuming you're using the quickstartdocker run
command)/etc/sourcegraph/nginx.conf
inside the container
SSL support requires manual editing of the NGINX configuration file if using the quickstart docker run command as it presumes local or internal usage.
Sourcegraph Cluster (Kubernetes)
We use the ingress-nginx for Sourcegraph Cluster running on Kubernetes. Refer to the deploy-sourcegraph Configuration documentation for more information.
NGINX SSL/HTTPS configuration
If you have a valid SSL certificate
1. Copy your SSL certificate and key to ~/.sourcegraph/config
(where the nginx.conf
file is).
2. Edit 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 / { ... } } }
If you need an SSL certificate
There are a few options:
1. Generate a browser-trusted certificate using Let's Encrypt (Certbot)
-
On the Certbot homepage, select "Nginx" and the operating system of the machine hosting Sourcegraph.
-
Follow the instructions to install and run Certbot.
-
If there is currently a process (e.g., Sourcegraph) listening on port 80, you'll need to stop it before running Certbot:
docker stop $(docker ps | grep sourcegraph/server | awk '{ print $1 }')
-
When you get to the step describing how to run Certbot, use the "certonly" command:
sudo certbot certonly --nginx
. -
When Certbot runs successfully, it will emit the key file
privkey.pem
and cert filefullchain.pem
. These should be renamed tosourcegraph.key
andsourcegraph.crt
, respectively, if you are using thenginx.conf
template mentioned in this doc. -
Kill the NGINX server that Certbot started:
killall nginx
. Restart Sourcegraph:docker start $(docker ps -a | grep sourcegraph/server | awk '{ print $1 }')
-
Now visit your Sourcegraph instance at
https://${YOUR_URL}
. If there are issues, debug by examining the Docker logs:docker logs $(docker ps | grep sourcegraph/server | awk '{ print $1 }')
2. Generate a self-signed certificate
For instances that don't yet have a certificate from a globally trusted Certificate Authority (CA) provider.
3. Use your CDN's HTTPS proxy feature
Some CDNs such as Cloudflare can handle the HTTPS connection from the user's browser while allowing the underlying service to continue serving HTTP (or HTTPS with a self-signed certificate). View your CDN's documentation for more details.
Redirect to external HTTPS URL
The URL that clients should use to access Sourcegraph is defined in the externalURL
property in site configuration. To enforce that clients access Sourcegraph via this URL (and not some other URL, such as an IP address or other non-https
URL), add the following to nginx.conf
(replacing https://sourcegraph.example.com
with your external URL):
# Redirect non-HTTPS traffic to HTTPS. server { listen 80; server_name _; location / { return 301 https://sourcegraph.example.com$request_uri; } }
HTTP Strict Transport Security
HTTP Strict Transport Security instructs web clients to only communicate with the server over HTTPS. To configure it, add the following to nginx.conf
(in the server
block):
add_header Strict-Transport-Security "max-age=31536000; includeSubDomains" always;
See add_header
documentation and "Configuring HSTS in nginx" for more details.
Additional NGINX SSL configuration
See the NGINX SSL Termination guide and Configuring HTTPS Servers.
Next steps
You should configure Sourcegraph's externalURL
in the site configuration (and restart the frontend instances) so that Sourcegraph knows its URL.
Sourcegraph via Docker Compose: Caddy 2
Sourcegraph's Docker Compose deployment uses Caddy 2 as its reverse proxy. The Docker Compose deployment ships with a few builtin templates that cover common scenarios for exposing Sourcegraph:
- plain HTTP
- HTTPS with automatically provisioned Let's Encrypt certificates
- HTTPS with custom certificates that you provide
Usage instructions are provided via the caddy
service's inline comments inside the docker-compose.yaml
definition.
Other Sourcegraph clusters (e.g. pure-Docker)
NGINX is not included in the (pure-Docker deployment as it's designed to be minimal and not tied to any specific reverse proxy.
If NGINX is your preferred reverse proxy, we suggest using the official NGINX docker images and following their instructions for securing HTTP traffic with a proxied server.