Sourcegraph Learn

How to install Sourcegraph with Docker Compose

Lisa Tagliaferri
Published on September 30, 2021

Sourcegraph is a universal code search tool, allowing you to search across your own code or public open source repositories that you add to your instance. You can begin experimenting with Sourcegraph through Sourcegraph Cloud, which is available in-browser and has millions of open source repositories indexed.

Once you know that you would like to self-host your own instance of Sourcegraph to search across your local or cloud repositories, and you want it to be suitable for a production environment, you can follow along with this tutorial that will set you up with a Sourcegraph instance on Docker Compose. This tutorial will assume *nix commands on the command line.

If, instead, you would like to perform a quick install of Sourcegraph with Docker, which is suitable for testing environments, you can do so by following one of our tutorials for Linux, cloud Linux, macOS, or Windows.

Installing Sourcegraph into your production environment can allow you to use advanced features of Sourcegraph. You can also review our installation documentation.

Prerequisites and estimating your setup needs#

To install Sourcegraph with Docker Compose, your setup will need to meet certain requirements. We recommend following the official documentation to install Docker and Docker Compose.

  • You have Docker installed, and it’s v20.10.0 or above.
  • You have Docker Compose installed, and it’s v1.22.0 or above.
  • Your machine or server has an estimated minimum number of 8 CPU cores.

Use the resource estimator to ensure that your machine meets the minimum requirements for your Sourcegraph instance needs based on the number of code repositories and number of users you are planning to set up on your instance.

Step 1 — Fork the reference repository#

First, you will need to create a fork of the sourcegraph/deploy-sourcegraph-docker reference repository.

You can fork the reference repository from GitHub’s user interface. Having a GitHub account is required when forking repositories that are hosted on GitHub.

To fork the repository using GitHub’s user interface, navigate to the reference repository. On the right-hand side of the top navigation pane, you will find a Fork button.

GitHub interface showing the Fork button on the Deploy Sourcegraph with Docker repo

When you click on the Fork button, GitHub will create a fork of the repository for you.

With the forked repository, you can make customizations that are tailored to your organization’s needs. The original repository will remain as a source of truth when you need to make updates or upgrades to your Sourcegraph instance.

Step 2 — Clone the forked repository#

After forking the reference repository, you may want to create a directory or move to a directory on your machine or host where the fork will live. Clone the forked repository into this directory, which is called the configuration directory.

For our example, we’ll move into a temporary directory, ~/tmp.


Enter the following command on your terminal to clone your forked repository. Be sure to substitute your username where we have your-username written out in the URL.


You should receive output similar to the following:

Cloning into 'deploy-sourcegraph-docker'... ... Resolving deltas: 100% (4418/4418), done.

Once you clone the Git repository, all the relevant code lives locally on your machine or server. You now have a copy of the reference repository that you can configure to suit your needs.

Step 3 — Add the reference repository as upstream remote#

A connection to the upstream repository you forked in Step 1 gives you the necessary connection to pull from the reference as needed. Remote repositories are versions of your project that are hosted online, in this case it is the main reference project maintained by Sourcegraph.

To set up your reference to the remote upstream repository, you’ll first need to move into the directory of your cloned repo. For our example, the path is the following, but be sure to use the path relevant to your machine and file structure.


From within the /deploy-sourcegraph-docker directory, use the following command that passes in the URL of the sourcegraph/deploy-sourcegraph-docker project to set up the remote upstream.


If everything was successful, you will be at a new line of your terminal, with no other output.

Because you have pull access, you can keep up with changes on the reference repository by pulling the main branch whenever there is an update.

Step 4 — Install Sourcegraph on your host#

Move to the configuration directory (the file path on your machine that contains the clone to the fork you created), and navigate to the Docker Compose folder.


Within this directory, you can spin up the Sourcegraph instance on your host with Docker Compose. Here, up -d refers to starting the containers in the background and leaving them running; the -d flag refers to running the containers in a detached mode.

docker-compose up -d

Once you run this, you will know that your installation was successful when you receive output that generates done messaging, and output that notifies you that Sourcegraph is ready. This will display with your server or localhost IP address and the relevant port.

Sourcegraph is ready at: [an-address-and-port-created-by-your-server]

You can access Sourcegraph using the relevant IP address and port number.

Step 5 — Check that the service is healthy#

After receiving the message that Sourcegraph is ready, you will need to check that the service is healthy by running the Docker process command or docker ps for short.

Sometimes, a service may be running but cannot respond to requests because a required step is not complete. Running a health check lets you know the actual state of the service.


The instance is healthy when the sourcegraph-frontend-0 image is running and is marked as “healthy” on your host’s terminal.

[your-container-id] sourcegraph-frontend-0 "/sbin/tini -- /usr/…" Up 20 minutes(healthy)

A service will be marked as healthy if it has fulfilled all the checks that it needs to run.

Step 6 — Access Sourcegraph with a browser#

Copy the IP address created by your server and access it with a web browser of your choice. The link leads to a page that lets you create an account to start using Sourcegraph.

Sourcegraph signup landing page

After successfully installing Sourcegraph with Docker Compose, you can create a Sourcegraph Account.

Next steps#

Now that you have Sourcegraph installed and you also have a Sourcegraph account, you can check out our Sourcegraph resources to find helpful guides on how to use Sourcegraph effectively.

You can also learn more about Sourcegraph by reviewing our product docs.