Deploying Sourcegraph executors using Docker Compose

A docker-compose file is provided to deploy executors standalone, or alongside your existing Sourcegraph deployment.

How it works

The executor service itself runs in a Docker container and polls Sourcegraph for work. After dequeuing a job, it clones the target repository into a workspace and uses the Docker daemon to run each job step sequentially in another container. Batch Changes jobs that do not use native execution invoke src; code navigation and native Batch Changes jobs invoke Docker directly. Logs and the final job status are streamed back to Sourcegraph.

On this page

• Requirements
• Deployment
• Upgrading executors
• Related configuration
• Security note

Requirements

Privileged containers are required to run executors in docker-compose. This is because executors require access to the docker daemon running on the host.

Deployment

Prerequisites

• Install Docker Compose on the server
• Minimum Docker v20.10.0 and Docker Compose v1.29.0
• Docker Swarm mode is not supported
• Clone the deploy-sourcegraph-docker
• Edit the deploy-sourcegraph-docker/docker-compose/executors/executor.docker-compose.yaml and update the environment variables
• Follow the instructions in the README for more specific deployment instructions.

Upgrading executors

Upgrading Docker Compose executors requires updating the executor image tag in the compose file and recreating the container. Check the changelog for any executor-related breaking changes or new features.

1. Navigate to the deploy-sourcegraph-docker repository and pull the latest changes for the target version:

   BASH
   cd deploy-sourcegraph-docker
   git fetch
   git checkout v<target version>

   If you are using a custom compose file rather than the one from the repository, update the image field for the executor service to the target version. For example, to upgrade to version 7.5.0:

   YAML
   services:
     executor:
       image: 'index.docker.io/sourcegraph/executor:7.5.0'

2. Recreate the executor container with the updated image:

   BASH
   cd docker-compose
   docker compose -f docker-compose.yaml -f executors/executor.docker-compose.yaml up -d executor

   If you are running executors on a standalone machine:

   BASH
   docker compose -f executor.docker-compose.yaml up -d

   Docker Compose will pull the new image and recreate the executor container. The executor will briefly disconnect during the restart.

3. Verify the new container is running with the expected image:

   BASH
   docker ps --filter name=executor --format 'table {{.Names}}\t{{.Image}}\t{{.Status}}'

4. Confirm the executor is online and reporting the expected version under Site admin > Executors > Instances.

Related configuration

• Add custom certificates to a Docker Compose deployment
• Use private container registries

Note

Executors deployed via Docker Compose do not use Firecracker, meaning they require privileged access to the Docker daemon running on the host.

If you have security concerns, consider deploying via terraform or installing the binary directly.