Quickstart step 1: Install dependencies

Sourcegraph has the following dependencies:

The following are two recommendations for installing these dependencies:


  1. Install Homebrew.

  2. Install Docker for Mac.

    optionally via brew

    brew cask install docker
  3. Install Go, Node Version Manager, PostgreSQL, Redis, Git, NGINX, golang-migrate, Comby, SQLite tools, and jq with the following command:

    brew install go yarn redis postgresql git gnu-sed nginx golang-migrate comby sqlite pcre FiloSottile/musl-cross/musl-cross jq watchman
  4. Install the Node Version Manager (nvm) using:

    NVM_VERSION="$(curl https://api.github.com/repos/nvm-sh/nvm/releases/latest | jq -r .name)"
    curl -L https://raw.githubusercontent.com/nvm-sh/nvm/"$NVM_VERSION"/install.sh -o install-nvm.sh
    sh install-nvm.sh

    After the install script is finished, re-source your shell profile (e.g., source ~/.zshrc) or restart your terminal session to pick up the nvm definitions. Re-running the install script will update the installation.

    Note: nvm is implemented as a shell function, so it may not show up in the output of which nvm. Use type nvm to verify whether it is set up. There is also a Homebrew package for nvm, but it is unsupported by the nvm maintainers.

    • For fish shell users, you will want to install bass which you can get via omf:

      curl -L https://get.oh-my.fish | fish
      omf install bass
    • Then add the following to your config.fish:

      function nvm
        bass source ~/.nvm/nvm.sh --no-use ';' nvm $argv
      set -x NVM_DIR ~/.nvm
  5. Install the current recommended version of Node JS by running the following from the working directory of a sourcegraph repository clone:

    nvm install
    nvm use --delete-prefix

    After doing this, node -v should show the same version mentioned in .nvmrc at the root of the sourcegraph repository.

    Note: Although there is a Homebrew package for Node, we advise using nvm instead, to ensure you get a Node version compatible with the current state of the sourcegraph repository.

  6. Configure PostgreSQL and Redis to start automatically

    brew services start postgresql
    brew services start redis

    (You can stop them later by calling stop instead of start above.)

  7. Ensure psql, the PostgreSQL command line client, is on your $PATH. Homebrew does not put it there by default. Homebrew gives you the command to run to insert psql in your path in the "Caveats" section of brew info postgresql. Alternatively, you can use the command below. It might need to be adjusted depending on your Homebrew prefix (/usr/local below) and shell (bash below).

    hash psql || { echo 'export PATH="/usr/local/opt/postgresql/bin:$PATH"' >> ~/.bash_profile }
    source ~/.bash_profile
  8. Open a new Terminal window to ensure psql is now on your $PATH.


  1. Add package repositories:

    # Go
    sudo add-apt-repository ppa:longsleep/golang-backports
    # Docker
    curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo apt-key add -
    sudo add-apt-repository "deb [arch=amd64] https://download.docker.com/linux/ubuntu $(lsb_release -cs) stable"
    # Yarn
    curl -sS https://dl.yarnpkg.com/debian/pubkey.gpg | sudo apt-key add -
    echo "deb https://dl.yarnpkg.com/debian/ stable main" | sudo tee /etc/apt/sources.list.d/yarn.list
  2. Update repositories:

    sudo apt-get update
  3. Install dependencies:

    sudo apt install -y make git-all postgresql postgresql-contrib redis-server nginx libpcre3-dev libsqlite3-dev pkg-config golang-go musl-tools docker-ce docker-ce-cli containerd.io yarn jq
    # install golang-migrate (you must rename the extracted binary to `golang-migrate` and move the binary into your $PATH)
    curl -L https://github.com/golang-migrate/migrate/releases/download/v4.7.0/migrate.linux-amd64.tar.gz | tar xvz
    # install comby (you must rename the extracted binary to `comby` and move the binary into your $PATH)
    curl -L https://github.com/comby-tools/comby/releases/download/0.11.3/comby-0.11.3-x86_64-linux.tar.gz | tar xvz
    # install watchman (you must put the binary and shared libraries on your $PATH and $LD_LIBRARY_PATH)
    curl -LO https://github.com/facebook/watchman/releases/download/v2020.07.13.00/watchman-v2020.07.13.00-linux.zip
    unzip watchman-*-linux.zip
    sudo mkdir -p /usr/local/{bin,lib} /usr/local/var/run/watchman
    sudo cp bin/* /usr/local/bin
    sudo cp lib/* /usr/local/lib
    sudo chmod 755 /usr/local/bin/watchman
    sudo chmod 2777 /usr/local/var/run/watchman
    # On Linux, you may need to run the following in addition:
    watchman watch <path to sourcegraph repository>
    # nvm (to manage Node.js)
    NVM_VERSION="$(curl https://api.github.com/repos/nvm-sh/nvm/releases/latest | jq -r .name)"
    curl -L https://raw.githubusercontent.com/nvm-sh/nvm/"$NVM_VERSION"/install.sh -o install-nvm.sh
    sh install-nvm.sh
    # in repo dir: install current recommendend version of Node JS
    nvm install
  4. Configure startup services

    sudo systemctl enable postgresql
    sudo systemctl enable redis-server.service
  5. (optional) You can also run Redis using Docker

    In this case you should not enable the redis-server.service from the previous step.

    dockerd # if docker isn't already running
    docker run -p 6379:6379 -v $REDIS_DATA_DIR redis
    # $REDIS_DATA_DIR should be an absolute path to a folder where you intend to store Redis data

    You need to have Redis running when you start the dev server later on. If you have issues running Docker, try adding your user to the docker group, and/or updating the socket file persimissions, or try running these commands under sudo.

(optional) asdf

asdf is a CLI tool that manages runtime versions for a number of different languages and tools. It can be likened to a language-agnostic version of nvm or pyenv.

We use asdf in buildkite to lock the versions of the tools that we use on a per-commit basis.


asdf binary

See the installation instructions on the official asdf documentation.


sourcegraph/sourcegraph uses the following plugins:

asdf plugin add golang
asdf plugin add nodejs

# Import the Node.js release team's OpenPGP keys to main keyring
bash ~/.asdf/plugins/nodejs/bin/import-release-team-keyring

# Have asdf read .nvmrc for auto-switching between node version
## Add the following to $HOME/.asdfrc:
legacy_version_file = yes
asdf plugin add yarn

Usage instructions

asdf uses versions specified in .tool-versions whenever a command is run from one of sourcegraph/sourcegraph's subdirectories.

You can install the all the versions specified in .tool-versions by running asdf install.

< Previous | Next >