Configuration

⚠️ We recommend using our machine image, which is much easier and offers more flexibility when configuring Sourcegraph. Existing customers can reach out to our Customer Support Engineering team [email protected] for assistance with migrating.

You can find the default base docker-compose.yaml file inside the deploy-sourcegraph-docker repository. We strongly recommend using an override file, instead of modifying the base docker-compose.yaml file.

To configure your Sourcegraph instance, see Sourcegraph's configuration docs.

What is an override file?

Docker Compose allows you to customize configurations using an override file, ex. docker-compose.override.yaml, which enables you to persist your configurations through upgrades, without having to manage merge conflicts when we update our base docker-compose.yaml file, as your changes are not made directly to the base file.

When you run docker compose commands, we recommend that you specify the compose files in the order of precedence. In this example, the values in the override file override any conflicting values in the base file. You can also provide multiple override files in a command, to help you manage multiple instances / environments / test configurations, etc.

BASH
docker compose -f docker-compose.yaml -f docker-compose.override.yaml up -d --remove-orphans

See the Docker Compose docs for details.

Adjust resources

You only need to specify the services and configurations which you need to override from the base file.

YAML
# docker-compose.override.yaml
services:
  gitserver-0:
    cpus: 8
    mem_limit: '32g'

Use external databases

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

You can alternatively configure Sourcegraph to use external services.

Set environment variables

Add / override an environment variable on the sourcegraph-frontend-0 service:

YAML
# docker-compose.override.yaml
services:
  sourcegraph-frontend-0:
    environment:
      - EXAMPLE_ENV_VAR=example_value

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

Enable HTTP tracing

Sourcegraph supports HTTP tracing to help troubleshoot issues. See Tracing for details.

The base docker-compose.yaml file enables the bundled otel-collector by default, but a tracing backend needs to be deployed or configured to see HTTP traces.

To enable tracing on your instance, you'll need to either:

Deploy our bundled Jaeger backend, or
Configure an external tracing backend

Once a tracing backend has been deployed, see our Tracing page for next steps, including required changes to your Site Configuration to enable traces.

Deploy the bundled Jaeger

To deploy the bundled Jaeger web UI to see HTTP trace data, add Jaeger's docker-compose.yaml override file to your deployment command.

BASH
docker compose \
    -f docker-compose/docker-compose.yaml \
    -f docker-compose/jaeger/docker-compose.yaml \
    -f docker-compose/docker-compose.override.yaml \
    up -d --remove-orphans

Configure an external tracing backend

The bundled otel-collector can be configured to export HTTP traces to an OTel-compatible backend of your choosing.

To customize the otel-collector config file:

Create a copy of the default config in otel-collector/config.yaml
Follow the OpenTelemetry collector configuration guidance
Edit your docker-compose.override.yaml file to mount your custom config file to the otel-collector container:

YAML
services:
  otel-collector:
    command: ['--config', '/etc/otel-collector/config.yaml']
    volumes:
      - '~/deploy-docker-compose/otel-collector/custom-config.yaml:/etc/otel-collector/config.yaml'

Git configuration

Git SSH configuration

Provide your gitserver container with SSH / Git configuration needed to connect to some code hosts, by mounting a directory that contains the needed config files into the gitserver container, ex.

.ssh/config
.ssh/id_rsa.pub
.ssh/id_rsa
.ssh/known_hosts

You can also provide other files like .netrc, .gitconfig, etc. at their respective paths, if needed.

YAML
# docker-compose.override.yaml
services:
  gitserver-0:
    volumes:
      - 'gitserver-0:/data/repos'
      - '~/sg/volume-maps/gitserver/.ssh:/home/sourcegraph/.ssh'

WARNING: The permissions on your SSH / Git configuration must be set to be readable by the user in the gitserver container. For example, run chmod -v -R 600 ~/sg/volume-maps/gitserver/.ssh in the folder on the host machine.

Git HTTP(S) basic username + password authentication

The easiest way to specify basic authentication usernames and passwords code hosts which require basic authentication, is to include them in the clone URL itself, ex. https://user:[email protected]/my/repo. These credentials won't be displayed to non-admin users.

If you must use a .netrc file to store these credentials instead, follow the previous example for mounting SSH configuration, to mount a .netrc file from the host to /home/sourcegraph/.netrc in the gitserver container.

Add replicas

When adding replicas for gitserver, indexed-search, searcher, or symbols, you must update the corresponding environment variable on each of the frontend services in your docker-compose.override.yaml file, SRC_GIT_SERVERS, INDEXED_SEARCH_SERVERS, SEARCHER_URL, and SYMBOLS_URL to the number of replicas for each respective service. Sourcegraph will then automatically infer the endpoints for each replica.

YAML
# docker-compose.override.yaml
services:
 
  sourcegraph-frontend-0:
    environment:
      - 'SRC_GIT_SERVERS=2'
      - 'INDEXED_SEARCH_SERVERS=2'
      - 'SEARCHER_URL=1'
      - 'SYMBOLS_URL=1'
 
  sourcegraph-frontend-internal:
    environment:
      - 'SRC_GIT_SERVERS=2'
      - 'INDEXED_SEARCH_SERVERS=2'
      - 'SEARCHER_URL=1'
      - 'SYMBOLS_URL=1'

Shard gitserver

If you find that your gitserver container is performing poorly, you can shard it into multiple containers. This is especially helpful when your Docker Compose host can mount multiple storage volumes, and each gitserver shared can use its own storage IOPS limit.

To split gitserver across multiple shards:

YAML
# docker-compose.override.yaml
services:
# Adjust resources for gitserver-0
# And then create an anchor to share with the replica
  gitserver-0: &gitserver
    cpus: 8
    mem_limit: '32g'
# Create a new service called gitserver-1,
# which is an extension of gitserver-0
  gitserver-1:
  # Extend the original gitserver-0 to reuse most values
    extends:
      file: docker-compose.yaml
      service: gitserver-0
    # Use the new resources values from gitserver-0 above
    <<: *gitserver
    # Since this is an extension of the original gitserver-0,
    # we will have to rename the container name to gitserver-1
    container_name: gitserver-1
    # Assign it to a new volume which we will create below in the volumes section
    volumes:
      - 'gitserver-1:/data/repos'
    # Assign a new host name so it doesn't use the gitserver-0 one
    hostname: gitserver-1
# Add the new replica to other related services as environment
  sourcegraph-frontend-0: &frontend
    cpus: 6
    mem_limit: '6g'
    # Set the following environment variables to generate the replica endpoints
    environment: &env_gitserver
      - 'SRC_GIT_SERVERS=2'
# Use the same override values as sourcegraph-frontend-0 above
  sourcegraph-frontend-internal:
    <<: *frontend
# Add the updated environment for gitserver from frontend to worker using anchor
  worker:
    environment:
      - *env_gitserver
# Add a new volume assigned to the new gitserver replica
volumes:
  gitserver-1:

Disable a service

You can disable services by assigning them to one or more profiles, so that when running the docker compose up command, services assigned to profiles will not be started unless explicitly specified in the command (e.g., docker compose --profile disabled up).

For example, when you need to disable the bundled databases to use external databases, you can assign the bundled database containers to a profile called disabled:

YAML
# docker-compose.override.yaml
services:
  codeintel-db:
    profiles:
      - disabled

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:

YAML
# docker-compose.override.yaml
services:
  sourcegraph-frontend-0:
    ports:
      - '0.0.0.0:6060:6060'

For specific ports that can be exposed, see the debug ports section of the pprof profiling data page.