Deployment - Sourcegraph

Sourcegraph supports two primary self-hosted deployment methods. Choose based on your scale and operational capabilities.

	Docker Compose	Kubernetes (Helm)
Best for	Small to medium teams	Large enterprises
Node count	Single node	Multi-node
Scaling	Vertical	Horizontal
Complexity	Lower	Higher
Recommended size	Up to ~M (5,000 users)	Any scale

Changing deployment methods after initial setup requires a full redeployment and database migration. Choose the right method for your long-term needs before going to production.

Docker Compose
Kubernetes (Helm)

Docker Compose deployment

Docker Compose runs all Sourcegraph services as containers on a single host. It is easier to operate than Kubernetes and works well for teams up to a few thousand users.

Prerequisites

Docker v20.10.0 or later
Docker Compose v1.29.0 or later (Docker Swarm mode is not supported)
A Linux server with SSD storage (see system requirements)
A Sourcegraph Enterprise license for instances with more than 10 users

Running Sourcegraph on Windows or ARM/ARM64 is not supported for production deployments.

Installation

Fork the deployment repository

The sourcegraph/deploy-sourcegraph-docker repository contains the docker-compose.yaml and all supporting configuration.Create a private copy of this repository in your own code host. Storing your customizations in version control makes upgrades much simpler — you track changes as a diff against the upstream repository.

# Bare clone the deployment repo
git clone --bare https://github.com/sourcegraph/deploy-sourcegraph-docker/

# Mirror push to your private repository
cd deploy-sourcegraph-docker.git
git push --mirror https://github.com/your-org/sourcegraph-deploy.git

# Clean up the bare clone
cd ..
rm -rf deploy-sourcegraph-docker.git

Create a release branch

Clone your private repository and create a release branch pinned to the version you want to install:

git clone https://github.com/your-org/sourcegraph-deploy.git
cd sourcegraph-deploy

# Add the upstream repo so you can pull future releases
git remote add upstream https://github.com/sourcegraph/deploy-sourcegraph-docker

# Check out a release branch from the desired version tag
export SOURCEGRAPH_VERSION=6.5.0
git checkout $SOURCEGRAPH_VERSION -b release

Customize the instance

Do not edit docker-compose.yaml directly. Instead, create a docker-compose.override.yaml file in the same directory. The override file is merged with the base config, so your changes survive upstream updates without merge conflicts.Common customizations in the override file:

Adjust CPU and memory limits for individual services
Add replicas for high-traffic services
Connect to an external PostgreSQL or Redis
Set environment variables
Mount custom TLS certificates

Commit the override file to your release branch.

Clone to the production server

On your production server, clone the release branch:

git clone --branch release https://github.com/your-org/sourcegraph-deploy.git

Start Sourcegraph

From the docker-compose directory, start all services:

cd docker-compose
docker compose up -d

Check that the frontend is healthy:

docker ps --filter="name=sourcegraph-frontend-0"

Once the sourcegraph-frontend-0 container shows as healthy, navigate to your server’s IP or hostname on port 80. You will be prompted to create the initial site admin account.

Apply site configuration

After signing in as the initial admin, go to Site admin > Configuration to set your externalURL, connect code hosts, configure authentication, and add your license key. See Site configuration for details.

Upgrading (Docker Compose)

Upgrades are performed by updating the release branch to a newer version tag and redeploying.

Fetch upstream tags

git fetch upstream

Merge the new version

export NEW_VERSION=6.6.0
git merge $NEW_VERSION

Resolve any merge conflicts. Your docker-compose.override.yaml should not conflict with the base file.

Pull new images and restart

On the production server, pull the updated repository and restart services:

git pull
cd docker-compose
docker compose pull
docker compose up -d

Always read the changelog for the versions you are upgrading through. Some versions require specific migration steps before restarting.

Kubernetes with Helm deployment

Sourcegraph’s Helm chart is the recommended deployment method for large enterprises. It supports multi-node clusters, horizontal scaling, and integrates with managed Kubernetes services on GKE, EKS, and AKS.

Prerequisites

Kubernetes 1.19 or later
Helm 3 CLI
A CSI storage driver for persistent volumes (e.g., AWS EBS CSI, GCP persistent disk, Azure Disk)
An Ingress Controller (e.g., NGINX, AWS ALB Controller, GCP HTTP Load Balancing)
Ability to create DNS records for your Sourcegraph domain

Sourcegraph uses Server-Sent Events (SSE) for streaming search results. Your ingress controller or load balancer must allow connections to remain open for at least 5 minutes. Many ingress controllers default to shorter timeouts which will cause streaming to fail.

Installation

Add the Sourcegraph Helm repository

helm repo add sourcegraph https://helm.sourcegraph.com/release

Create an override file

Create an override.yaml file for your customizations. Do not copy the full default values.yaml as a starting point — only include the values you need to change. This prevents stale values from causing issues during future upgrades.At minimum, configure your ingress hostname and storage class. Here is an example for a generic cluster:

frontend:
  ingress:
    enabled: true
    annotations:
      kubernetes.io/ingress.class: nginx
    host: sourcegraph.example.com

storageClass:
  create: true
  provisioner: your-csi-provisioner
  volumeBindingMode: WaitForFirstConsumer
  reclaimPolicy: Retain

Store your override file in version control.

Deploy Sourcegraph

helm upgrade --install \
  --values ./override.yaml \
  --version 6.5.0 \
  sourcegraph sourcegraph/sourcegraph

Monitor the rollout:

kubectl get pods --watch

When all pods show as Running, Sourcegraph is ready.

Configure DNS and TLS

Get the load balancer address:

kubectl describe ingress sourcegraph-frontend

Create a DNS A record (or CNAME) pointing sourcegraph.example.com to the load balancer address.Configure TLS using your preferred method: a cloud-managed certificate, cert-manager with Let’s Encrypt, or a manually created TLS Secret.

Apply site configuration

Navigate to your Sourcegraph URL and create the initial admin account. Then go to Site admin > Configuration to configure code hosts, auth providers, and your license key.

Cloud provider guides

Platform-specific configuration is required for ingress and storage class settings:

Google GKE

frontend:
  serviceType: ClusterIP
  ingress:
    enabled: true
    annotations:
      kubernetes.io/ingress.class: gce
  serviceAnnotations:
    cloud.google.com/neg: '{"ingress": true}'
    beta.cloud.google.com/backend-config: '{"default": "sourcegraph-frontend"}'

storageClass:
  create: true
  type: pd-ssd
  provisioner: pd.csi.storage.gke.io
  volumeBindingMode: WaitForFirstConsumer
  reclaimPolicy: Retain

GKE requires a BackendConfig resource for health check configuration. See the GKE example override for the full file including the BackendConfig.Note: GKE Autopilot clusters are not supported.

AWS EKS

Requires the AWS Load Balancer Controller and AWS EBS CSI driver add-ons.

frontend:
  ingress:
    enabled: true
    annotations:
      alb.ingress.kubernetes.io/target-type: ip
      kubernetes.io/ingress.class: alb
    host: sourcegraph.example.com

storageClass:
  create: true
  type: gp2
  volumeBindingMode: WaitForFirstConsumer
  reclaimPolicy: Retain

Azure AKS

Requires the Azure Application Gateway Ingress Controller and Azure Disk CSI driver.

frontend:
  ingress:
    enabled: true
    annotations:
      kubernetes.io/ingress.class: azure/application-gateway
    host: sourcegraph.example.com

storageClass:
  create: true
  provisioner: disk.csi.azure.com
  volumeBindingMode: WaitForFirstConsumer
  reclaimPolicy: Retain
  parameters:
    storageaccounttype: Premium_LRS

You must create your AKS cluster with CSI storage driver support enabled — this cannot be enabled after cluster creation.

Using external databases

For production deployments, use external managed PostgreSQL and Redis instead of the bundled services. Store credentials in Kubernetes Secrets:

apiVersion: v1
kind: Secret
metadata:
  name: pgsql-credentials
data:
  database: ''      # base64-encoded
  host: ''
  password: ''
  port: ''
  user: ''

Reference the secrets in your override.yaml:

pgsql:
  enabled: false
  auth:
    existingSecret: pgsql-credentials

codeIntelDB:
  enabled: false
  auth:
    existingSecret: codeintel-db-credentials

codeInsightsDB:
  enabled: false
  auth:
    existingSecret: codeinsights-db-credentials

Upgrading (Kubernetes/Helm)

Standard upgrade (one minor version at a time):

# Update the Helm repo
helm repo update sourcegraph

# Upgrade to the new version
helm upgrade --install \
  --values ./override.yaml \
  --version 6.6.0 \
  sourcegraph sourcegraph/sourcegraph

# Watch pods restart
kubectl get pods --watch

You can only upgrade one minor version at a time with a standard upgrade. To jump multiple versions, use a multi-version upgrade (MVU) with the migrator tool.

Multi-version upgrade: Scale down database-accessing services, run the migrator to apply database migrations, then upgrade the Helm chart.

# Scale down services
kubectl get -n sourcegraph deploy --no-headers | \
  awk '{print $1}' | \
  xargs -n 1 -I % kubectl -n sourcegraph scale deployment % --replicas=0

# Run migrator
helm upgrade --install -n sourcegraph \
  --set "migrator.args={upgrade,--from=6.0.0,--to=6.5.0}" \
  sourcegraph-migrator sourcegraph/sourcegraph-migrator \
  --version 6.5.0

# Then run the standard upgrade
helm upgrade --install -f override.yaml \
  --version 6.5.0 \
  sourcegraph sourcegraph/sourcegraph

Always check the changelog for migration notes before upgrading.

Resource requirements

Use the table below to estimate the resources needed for your deployment. If you fall between sizes, choose the larger one.

Size	Users	Repositories	vCPU	Memory	Storage
XS	≤ 500	≤ 5,000	8	32 GB	SSD
S	≤ 1,000	≤ 10,000	16	64 GB	SSD
M	≤ 5,000	≤ 50,000	32	128 GB	SSD
L	≤ 10,000	≤ 100,000	48	192 GB	SSD
XL	≤ 20,000	≤ 250,000	96	384 GB	SSD

Recommended cloud instance types:

Size	AWS	Azure	GCP
XS	m6a.2xlarge	D8_v3	n2-standard-8
S	m6a.4xlarge	D16_v3	n2-standard-16
M	m6a.8xlarge	D32_v3	n2-standard-32
L	m6a.12xlarge	D48_v3	n2-standard-48
XL	m6a.24xlarge	D64_v3	n2-standard-96

After deployment

Once Sourcegraph is running, complete the initial setup:

Set externalURL in site config to your instance’s public URL.
Add code host connections so Sourcegraph can clone and index your repositories.
Configure authentication with your identity provider.
Apply your license key to unlock Enterprise features.
Configure SMTP so Sourcegraph can send email notifications.

See Administration overview and Site configuration for detailed guidance on each step.

​Docker Compose deployment

​Prerequisites

​Installation

​Upgrading (Docker Compose)

​Kubernetes with Helm deployment

​Prerequisites

​Installation

​Cloud provider guides

​Using external databases

​Upgrading (Kubernetes/Helm)

​Resource requirements

​After deployment

Docker Compose deployment

Prerequisites

Installation

Upgrading (Docker Compose)

Kubernetes with Helm deployment

Prerequisites

Installation

Cloud provider guides

Using external databases

Upgrading (Kubernetes/Helm)

Resource requirements

After deployment