Sourcegraph with Docker Compose

⚠️ We recommend new users use our machine image or script-install instructions, which are easier and offer more flexibility when configuring Sourcegraph. Existing customers can reach out to our Customer Engineering team [email protected] if they wish to migrate to these deployment models.

Setting up Docker applications with multiple containers like Sourcegraph using Docker Compose allows us to start all the applications with a single command. It also makes configuring the applications easier through updating the docker-compose.yaml and docker-compose.override.yaml files. Please see the official Docker Compose docs to learn more about Docker Compose.

This guide will take you through how to install Sourcegraph with Docker Compose on a server, which could be the local machine, a server on a local network, or cloud-hosted server. You can also follow one of the available cloud-specific guides listed below to prepare and install Sourcegraph on a supported cloud environment:

Prerequisites

• Install Docker Compose on the server
  • Minimum Docker v20.10.0 and Docker Compose v1.29.0
  • Docker Swarm mode is not supported
• Check the resource estimator for resource requirements
• Obtain a Sourcegraph license
  • License is required for instances with more than 10 users
• optional Configure ingress firewall rules to enable secure access to the server

Installation Steps

A step by step guide to install Sourcegraph with Docker Compose.

Overview

1. RECOMMENDED Prepare the deployment repository
2. Customize the instance
3. Clone the release branch
4. Build and start the Sourcegraph containers

Step 1: Fork the deployment repository

sourcegraph/deploy-sourcegraph-docker is the deployment repository for Docker Compose---it contains everything you need to install and configure a Sourcegraph Docker Compose instance.

RECOMMENDED We strongly recommend you to deploy Sourcegraph using your own fork (or private copy) of the deployment repository as this allows you to track customizations made to the Sourcegraph docker-compose.yaml easily. It also makes upgrading your instance easier in the future.

Create a public or private copy of the deployment repository

Use the GitHub GUI to create a public fork of the sourcegraph/deploy-sourcegraph-docker deployment repository

  git clone --bare https://github.com/sourcegraph/deploy-sourcegraph-docker/

  cd deploy-sourcegraph-docker.git
  git push --mirror https://github.com/<you/private-repository>.git

  cd ..
  rm -rf deploy-sourcegraph-docker.git

# Please make sure to discard the token after the deployment for security purpose
https://<PERSONAL-ACCESS-TOKEN>@github.com/<USERNAME>/<REPO>.git

Configure your deployment repository

Continue with the following steps after you have created a public or private copy of the deployment repository:

1\. Clone the publicly forked (or privately cloned) repository to your local machine.

  git clone https://github.com/<you/private-repository>.git 

2\. Add the deployment repository maintained by Sourcegraph as the remote upstream.

• This is to keep your clone synced with the upstream repository.

  git remote add upstream https://github.com/sourcegraph/deploy-sourcegraph-docker

3\. Create a new branch called release off the latest version of Sourcegraph

• This branch will be used to upgrade Sourcegraph and install your Sourcegraph instance.
• It also allows us to track all of the customizations made to your Sourcegraph instance.

  # Specify the version you want to install
  export SOURCEGRAPH_VERSION="v5.0.0"
  # Check out the selected version for use, in a new branch called "release"
  git checkout $SOURCEGRAPH_VERSION -b release

Step 2: Configure the Instance

You can find the default docker-compose.yaml file inside the deployment repository.

If you would like to make changes to the default configurations, we highly recommend you create a new file called docker-compose.override.yaml in the same directory where the default docker-compose.yaml file is located, and make your customizations inside the docker-compose.override.yaml file.

• Here is a list of customizations you can make using an override file:
  • Add replicas
  • Adjust resources
  • Connect to an external database
  • Disable a service
  • Expose debug port
  • Git SSH configuration
  • Update or add new environment variables
  • And more!

Please make sure to commit any changes to your release branch.

For detailed instructions on how to configure the instance using an override file, please refer to the configuration docs.

Step 3: Clone the release branch

Now that you have customized your instance and published the changes to your code host, you will need to clone the newly configured release branch onto the production server:

  git clone --branch release https://github.com/<you/private-repository>.git 

Step 4: Start Sourcegraph

On the production server, run the following command inside the ./docker-compose directory to build and start Sourcegraph:

  # Go to the docker-compose configuration directory
  cd docker-compose
  # Start Sourcegraph with Docker Compose
  docker-compose up
  # OR you can start Sourcegraph with Docker Compose in a detached mode
  docker-compose up -d

To check if the server is ready, the sourcegraph-frontend-0 service must be displayed as healthy:

  # Check the health status for sourcegraph-frontend-0
  docker ps --filter="name=sourcegraph-frontend-0"

Once the server is ready, navigate to the sourcegraph-frontend-0 hostname or IP address on port 80.

Additional Information

• Upgrade
• Management Operations
• HTTP and HTTPS/SSL configuration
• Site Administration Quickstart