Deployment Overview

Sourcegraph supports different deployment methods for different purposes. Each deployment type requires different levels of investment and technical understanding. What works best for you and your team 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.

In general:

  • For most customers, we recommend Sourcegraph Cloud, managed entirely by Sourcegraph.
  • For customers who want to self-host, we recommend one of the single-node deployment options.
  • For enterprise customers that require a multi-node, self-hosted deployment, we offer a Kubernetes option. We strongly encourage you to get in touch by emails ([email protected]) if you pursue this option.
  • If you are short on time and looking for a quick way to test Sourcegraph locally, consider running Sourcegraph via our Docker Single Container.

Get Sourcegraph on your code.

A single-tenant instance managed by Sourcegraph.

Sign up for a 30 day trial for your team.

Get free trial now

Deployment types

To start, you will need to decide your on deployment method, including Kubernetes with or without Helm, as they are noninterchangeable. In short, you cannot change your deployment type of a running instance.

Each of the deployment types listed below provides a different level of capability. As mentioned previously, you shall pick a deployment type based 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.

Sourcegraph 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.

Machine Images

RECOMMENDED Customized machine images allow you to spin up a preconfigured and customized Sourcegraph instance with just a few clicks, all in less than 10 minutes!

Currently available in the following hosts:

Docker Compose

We recommend Docker Compose for most production deployments due to how easily admins can install, configure, and upgrade Sourcegraph instances. It serves as a way to run multi-container applications on Docker using a defined Compose file format.

Docker Compose is used for single-host instances such as AWS EC2 or GCP Compute Engine. It does not provide multi-machine capability such as high availability.

Docker Compose scales to fit the needs of the majority of customers. Refer to the resource estimator to find the appropriate instance for you.

Kubernetes or Kubernetes with Helm

Kubernetes is recommended for non-standard deployments where Docker Compose is not a viable option.

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

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

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 teams without the ability to support this, please speak to your Sourcegraph contact about using Docker Compose instead.


Reference repositories

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.

For more information, follow the installation and configuration docs for your specific deployment type.

Configuration

Configuration at the deployment level focuses on ensuring your Sourcegraph deployment 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.

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