Sourcegraph with Docker Compose

Docker Compose is a tool for defining and running multi-container Docker applications (in this case, Sourcegraph!). With Docker Compose, you use a YAML file to configure your application’s services. Then, with a single command, you create and start all the services from your configuration. To learn more about Docker Compose, head over to Docker's Docker Compose docs.

For Sourcegraph customers who want a simplified single-machine deployment of Sourcegraph with easy configuration and low cost of effort to maintain, Sourcegraph with Docker Compose is an ideal choice.

Not sure if the Docker Compose deployment type is the right for you? Learn more about the various Sourcegraph deployment types in our Deployment overview section.

Installing Sourcegraph on Docker Compose

This section provides instruction for 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.

Alternatively, follow these links for cloud-specific guides on preparing the environment and installing Sourcegraph:

Prerequisites

  • Use the resource estimator to configure a server to host your Sourcegraph containers
  • Configure ingress firewall rules to enable secure access to the server
  • Configure access for the server to your deployment files
    • We will be using a Personal Access Token from GitHub in this example
  • Install Docker Compose on the server
  • Obtain a Sourcegraph license
    • You can run through these instructions without one, but you must obtain a license for instances of more than 10 users.

Installation

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

Overview

  1. Fork the Sourcegraph Docker Compose deployment repository
  2. Clone your fork of the reference repository locally
  3. Create a release branch on your clone
  4. Customize the Docker-Compose YAML file
  5. Publish changes to your release branch
  6. Clone your release branch onto your server
  7. Build and start the containers in detached mode

Step 1: Fork the Sourcegraph Docker Compose deployment repository

The sourcegraph/deploy-sourcegraph-docker repository contains everything you need to install and configure a Sourcegraph Docker Compose instance, and it will make upgrades far easier. We strongly recommend that you create and run Sourcegraph from your own fork of the reference repository to track customizations made to the Sourcegraph Docker Compose YAML file.

1\. Use the GithHub GUI to Create a fork of the sourcegraph/deploy-sourcegraph-docker reference repository.

Alternatively, if you are using GitHub and you want your fork to be private, create a private clone of the reference repository in your code host. This process can be performed on any machine with access to your code host:

2\. Create an empty private repository, for example <you/private-repository> in GitHub.

3\. Bare clone the reference repository.

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

4\. Navigate to the bare clone and mirror push it to your private repository.

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

5\. Remove your local bare clone.

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

Step 2: Clone the forked repository locally

Clone the forked repository to your local machine.

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

Step 3: Configure the release branch

  1. Add the reference repository as the remote upstream in order to keep your fork synced with the upstream repository.
  git remote add upstream https://github.com/sourcegraph/deploy-sourcegraph-docker
  1. Create a release branch to track all of your customizations to Sourcegraph. This branch will be used to upgrade Sourcegraph and install your Sourcegraph instance.
  # Specify the version you want to install
  export SOURCEGRAPH_VERSION="v3.43.2"
  # Check out the selected version for use, in a new branch called "release"
  git checkout $SOURCEGRAPH_VERSION -b release

Step 4: Configure the YAML file

The reference repository includes a docker-compose.yaml file with a basic configuration. Adjust the service resources for your environment using the resource estimator then commit the changes to your release branch. The following section represents a number of key configuration items for your deployment.

Enable tracing

Check that tracing is enabled in the docker-compose.yaml file. The environment variable should be set to SAMPLING_STRATEGIES_FILE=/etc/jaeger/sampling_strategies.json in the jaeger container section:

jaeger:
  container_name: jaeger
  # ...
  environment:
    - 'SAMPLING_STRATEGIES_FILE=/etc/jaeger/sampling_strategies.json'

Git configuration

Git SSH configuration

Provide your gitserver instance with your SSH / Git configuration (e.g. .ssh/config, .ssh/id_rsa, .ssh/id_rsa.pub, and .ssh/known_hosts--but you can also provide other files like .netrc, .gitconfig, etc. if needed) by mounting a directory that contains this configuration into the gitserver container.

For example, in the gitserver-0 container configuration in your docker-compose.yaml file, add the volume listed in the following example, replacing ~/path/on/host/ with the path on the host machine to the .ssh directory:

gitserver-0:
  container_name: gitserver-0
  ...
  volumes:
    - 'gitserver-0:/data/repos'
    - '~/path/on/host/.ssh:/home/sourcegraph/.ssh'
  ...
Git HTTP(S) authentication

The easiest way to specify HTTP(S) authentication for repositories is to include the username and password in the clone URL itself, such as https://user:[email protected]/my/repo. These credentials won't be displayed to non-admin users.

Otherwise, follow the previous steps for mounting SSH configuration to mount a host directory containing the desired .netrc file to /home/sourcegraph/ in the gitserver container.

Expose debug port

To generate pprof profiling data, you must configure your deployment to expose port 6060 on one of your frontend containers, for example:

  sourcegraph-frontend-0:
    container_name: sourcegraph-frontend-0
    # ...
+   ports:
+     - '0.0.0.0:6060:6060'

For specific ports that can be exposed, see the debug ports section of Sourcegraphs's generate pprof profiling data docs.

Use an external database

The Docker Compose configuration has its own internal PostgreSQL and Redis databases.

To preserve this data when you kill and recreate the containers, review Sourcegraph's External Services for additional information on how you can use external services for persistence.

Set environment variables

Add/modify the environment variables to all of the sourcegraph-frontend-* services and the sourcegraph-frontend-internal service in the Docker Compose YAML file:

sourcegraph-frontend-0:
  # ...
  environment:
    # ...
    - (YOUR CODE)
    # ...

See "Environment variables in Compose" for other ways to pass these environment variables to the relevant services (including from the command line, a .env file, etc.).

Step 5: Update your release branch

Publish the customized configuration to the release branch you created earlier:

  git add .
  git commit -m "customize docker-compose.yaml for environment"
  git push origin release

Step 6: Clone the release branch remotely

Now that you have published your changes to your code host you deploy your customized codebase on the production server. Clone the newly configured release branch onto the production server.

Clone the release branch you've created earlier onto your server:

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

Step 7: Start Sourcegraph

On the production server, run the following command inside the docker-compose configuration directory to start Sourcegraph in a detached mode:

  # Go to the docker-compose configuration directory
  cd docker-compose
  # 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.

Next: Management Operations >