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.
- PostgreSQL Guide
- See Using your PostgreSQL server to replace the bundled PostgreSQL instances.
- See Using your Redis server to replace the bundled Redis instances.
- See Using a managed object storage service (S3 or GCS) to replace the bundled MinIO instance.
- See Using an external Jaeger instance in our tracing documentation to replace the bundled Jaeger instance.Use-an-external-Jaeger-instance
Cloud alternatives
- Amazon Web Services: AWS RDS for PostgreSQL, Amazon ElastiCache, and S3 for storing user uploads.
- Google Cloud: Cloud SQL for PostgreSQL, Cloud Memorystore, and Cloud Storage for storing user uploads.
- Digital Ocean: Digital Ocean Managed Databases for Postgres, Redis, and Spaces for storing user uploads.
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.