# Configuration

> ⚠️ We recommend using our [machine image](/self-hosted/deploy/machine-images/), which is much easier and offers more flexibility when configuring Sourcegraph. Existing customers can reach out to our Customer Support Engineering team support@sourcegraph.com for assistance with migrating.

You can find the default base [docker-compose.yaml](https://github.com/sourcegraph/deploy-sourcegraph-docker/blob/master/docker-compose/docker-compose.yaml) file inside the [deploy-sourcegraph-docker](https://github.com/sourcegraph/deploy-sourcegraph-docker/blob/master/docker-compose) 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](/admin/) 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](https://docs.docker.com/compose/extends/) 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](/self-hosted/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"](https://docs.docker.com/compose/environment-variables/) for other ways to pass these environment variables to the relevant services (command line, .env file, etc.).

## Enable tracing

Sourcegraph supports tracing to help troubleshoot issues. See [Tracing](/self-hosted/observability/tracing) for details.

The base docker-compose.yaml file enables the bundled [otel-collector](https://sourcegraph.com/search?q=repo:%5Egithub%5C.com/sourcegraph/deploy-sourcegraph-docker$+file:docker-compose/docker-compose.yaml+content:%22++otel-collector:%22&patternType=keyword) by default, but a tracing backend needs to be deployed or configured to see traces.

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

1. Deploy our bundled Jaeger backend, or
2. Configure an external tracing backend

Once a tracing backend has been deployed, see our [Tracing](/self-hosted/observability/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 trace data, add [Jaeger's docker-compose.yaml override file](https://github.com/sourcegraph/deploy-sourcegraph-docker/blob/main/docker-compose/jaeger/docker-compose.yaml) 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 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](https://github.com/sourcegraph/deploy-sourcegraph-docker/blob/main/otel-collector/config.yaml)
- Follow the [OpenTelemetry collector configuration guidance](/self-hosted/observability/opentelemetry)
- 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:password@example.com/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`, `searcher`, `zoekt-indexserver`, or `zoekt-webserver`, you must update the corresponding environment variable on each of the frontend services in your docker-compose.override.yaml file to the number of replicas for the respective service. Sourcegraph will then automatically infer the containers' endpoints for each replica.

```yaml
# docker-compose.override.yaml
services:
    sourcegraph-frontend-0:
        environment:
            - 'INDEXED_SEARCH_INDEXERS=1'
            - 'INDEXED_SEARCH_SERVERS=1'
            - 'SEARCHER_URL=1'
            - 'SRC_GIT_SERVERS=1'

    sourcegraph-frontend-internal:
        environment:
            - 'INDEXED_SEARCH_INDEXERS=1'
            - 'INDEXED_SEARCH_SERVERS=1'
            - 'SEARCHER_URL=1'
            - 'SRC_GIT_SERVERS=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 shard 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](https://docs.docker.com/compose/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](/self-hosted/pprof), 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](/self-hosted/pprof#debug-ports) section of the [pprof profiling data](/self-hosted/pprof) page.