Quickstart step 1: Install dependencies

Sourcegraph has the following dependencies:

You can choose to install Redis and/or PostgreSQL directly on your system, or you can run them as docker containers with docker compose. The following instructions will describe both options.

Running within a container provides some advantages such as storing the data separately from the container, you do not need to run it as a system service and its easy to use different database versions or multiple databases.

Running as system services might yield better performance, especially on macOS.

No matter which option you choose, docker is required because the development server starts additional docker containers.

The following are two recommendations for installing these dependencies:

macOS

  1. Install Homebrew.

  2. Install Docker for Mac.

    optionally via brew

    brew install --cask docker
    
  3. Install Go, Yarn, Git, golang-migrate, Comby, SQLite tools, and jq with the following command:

    brew install go yarn git gnu-sed golang-migrate comby sqlite pcre FiloSottile/musl-cross/musl-cross jq watchman
    
  4. (without docker) Install PostgreSQL and Redis

    If you want to run Redis and/or PostgreSQL directly on your system install them with the follwing command:

    brew install postgresql
    brew install redis
    
  5. (with docker) Install Docker Compose

    We provide a docker compose file at dev/redis-postgres.yml to make it easy to run Redis and PostgreSQL as docker containers. Fortunately docker-compose comes with Docker for Mac so no additional step is required.

    See the official docker compose documentation.

  6. 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.

    • 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
      end
      
      
      set -x NVM_DIR ~/.nvm
      
  7. 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.

  8. (optional) Configure PostgreSQL and Redis to start automatically

    If you have installed PostgreSQL and Redis directly on your system, start them with the following commands:

    brew services start postgresql
    brew services start redis
    

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

  9. 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
    
  10. Open a new Terminal window to ensure psql is now on your $PATH.

Ubuntu

  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 libpcre3-dev libsqlite3-dev pkg-config golang-go musl-tools docker-ce docker-ce-cli containerd.io yarn jq libnss3-tools
    # (without docker) install PostgreSQL and/or Redis if you don't want to run them as docker containers
    sudo apt install -y redis-server
    sudo apt install -y postgresql postgresql-contrib
    # 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. (with docker) Install Docker Compose

    We provide a docker compose file at dev/redis-postgres.yml to make it easy to run Redis and PostgreSQL as docker containers.

    See the official docker compose documentation for more details on different installation options.

  5. (without docker) Configure startup services

    If you have installed PostgreSQL and Redis directly on your system, start them with the following commands:

    sudo systemctl enable --now postgresql
    sudo systemctl enable --now redis-server.service
    

(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.

Install

asdf binary

See the installation instructions on the official asdf documentation.

Plugins

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 >