Sourcegraph NGINX HTTP and HTTPS/SSL configuration

In Sourcegraph 3.0+, NGINX acts 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.

NGINX for 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 quickstart docker 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.

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

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, replacing listen 7080; with listen 7080 ssl;, then add the following two lines below the listen 7080 ssl; statement.

ssl_certificate         sourcegraph.crt;
ssl_certificate_key     sourcegraph.key;

The nginx.conf should now look like this (names of cert and key can be anything):

...
http {
    ...
    server {
       ...
        listen 7080 ssl;
        ssl_certificate         sourcegraph.crt;
        ssl_certificate_key     sourcegraph.key;
        ...
    }
}

If you need an SSL certificate

There are a few options:

1. Generate a self-signed certificate
For instances that don't yet have certificate from a globally trusted Certificate Authority (CA) provider.

2. Generate a browser trusted certificate using Let's Encrypt (Certbot)
NGINX supported certificate management tool for programmatically obtaining a globally browser-trusted certificate.

3. Proxy as a service
Services such as Cloudflare can handle the SSL connection from the browser/client, proxying requests to your Sourcegraph instance.

Redirect to external HTTPS URL

The URL that clients should use to access Sourcegraph is defined in the externalURL property in critical 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 critical configuration (and restart the frontend instances) so that Sourcegraph knows its URL.