Deployment Overview

Sourcegraph supports two main deployment types: Docker Compose and Kubernetes. Each deployment type will require a different level of investment and technical understanding. What works best depends on the needs and desired outcomes for your business.

If you aren’t currently working with our Customer Engineering team, this overview will provide a high-level view of what’s available and needed depending on the deployment type you choose.

Specifically, the table provided in the Deployment types section will provide some high-level guidance, followed by more detailed descriptions for each type.

Sourcegraph also provides a resource estimator to help predict and plan the required resource for your deployment. This tool ensures you provision appropriate resources to scale your instance.

If you are short on time and looking for a quick way to test Sourcegraph locally, consider running Sourcegraph via our Docker Single Container.

To just use Sourcegraph on 2 million open-source repositories, visit Sourcegraph.com.

Resource planning

Sourcegraph has provided the Resource Estimator as a starting point to determine necessary resources based on the size of your deployment.

The Scaling Overview for Services docs provides a comprehensive overview of how each Sourcegraph service scales.

We recommend the Kubernetes deployment type if your deployment scenario includes a large codebase and many users. The Kubernetes docs provide additional information for scaling Kubernetes deployments.

Deployment types

Deployment Type Suggested for Setup time Resource isolation Auto-healing Multi-machine Complexity
Kubernetes with Helm Production deployments of any size 5 - 90 minutes YES YES YES Easy - Hard
Docker Compose Production deployments where Kubernetes with Helm is not viable 5 - 30 minutes YES YES NO Easy - Medium
Kubernetes without Helm Production deployments of any size 30 - 90 minutes YES YES YES Medium - Hard
Docker Single Container Local testing (Not recommended for production; no Code Insights support) 1 minute NO NO NO Easy

Each of the deployment types listed in the table above provides a different level of capability. As mentioned previously, base your deployment type on the needs of your business. However, you should also consider the technical expertise available for your deployment. The sections below provide more detailed recommendations for each deployment type.

Kubernetes with Helm

We recommend Kubernetes with Helm for most production deployments.

Kubernetes provides resource isolation (from other services or applications), automated-healing, and far greater ability to scale.

Helm provides a simple mechanism for deployment customizations, as well as a much simpler upgrade experience.

Docker Compose

Docker Compose is recommended for small and medium-size deployments where Kubernetes with Helm is not a viable option.

It does not provide multi-machine capability such as high availability, but will require less setup time overall.

Kubernetes without Helm

Before making a decision to deploy via Kubernetes without Helm, checkout our Kubernetes with Helm docs for additional information on why we recommend using Helm.

If you are unable to use Helm to deploy, but still want to use Kubernetes, follow our Kubernetes deployment documentation.

This path will require advanced knowledge of Kubernetes. For team’s without the ability to support this, please speak to your Sourcegraph contact about using Docker Compose instead.

Docker Single Container

The Docker Single container option is provided for local proof-of-concept only and is not intended for testing or deployment at a pre-production/production level.

Some features, such as Code Insights, are not available when using this deployment type.

Reference repositories

For Docker Compose,Kubernetes with Helm, and Kubernetes without Helm deployments, Sourcegraph provides reference repositories with branches corresponding to the version of Sourcegraph you wish to deploy. The reference repository contains everything you need to spin up and configure your instance depending on your deployment type, which also assists in your upgrade process going forward.

Before starting, you will need to decide your deployment type, including if you would like to use Kubernetes with Helm (vs. a more manual customization path). In the case of Kubernetes once you choose Helm (or not), it can’t be changed afterwards.

For more information, follow the install and configuration docs for your specific deployment type: Docker Compose, Kubernetes with Helm, or Kubernetes without Helm.

External services

By default, Sourcegraph provides versions of services it needs to operate, including:

  • A PostgreSQL instance for storing long-term information, such as user data, when using Sourcegraph’s built-in authentication provider instead of an external one.
  • A second PostgreSQL instance for storing large-volume code graph data.
  • A Redis instance for storing short-term information such as user sessions.
  • A second Redis instance for storing cache data.
  • A MinIO instance that serves as a local S3-compatible object storage to hold user uploads before processing. This data is for temporary storage, and content will be automatically deleted once processed.
  • A Jaeger instance for end-to-end distributed tracing.

External services guides

See the following guides to use an external or managed version of each service type.

Cloud alternatives

Configuration

Configuration at the deployment level focuses on ensuring your Sourcegraph runs optimally, based on the size of your repositories and the number of users. Configuration options will vary based on the type of deployment you choose. Consult the specific configuration deployment sections for additional information.

In addition you can review our Configuration docs for overall Sourcegraph configuration.

Operation

In general, operation activities for your Sourcegraph deployment will consist of storage management, database access, database migrations, and backup and restore. Details are provided with the instructions for each deployment type.

Monitoring

Sourcegraph provides a number of options to monitor the health and usage of your deployment. While high-level guidance is provided as part of your deployment type, you can also review our Observability docs for more detailed instruction.

Upgrades

A new version of Sourcegraph is released every month (with patch releases in between as needed). We actively maintain the two most recent monthly releases of Sourcegraph. The changelog provides all information related to any changes that are/were in a release.

Depending on your current version and the version you are looking to upgrade, there may be specific upgrade instruction and requirements. Checkout the Upgrade docs for additional information and instructions.