# Buildkite Agent Stack

> Buildkite agents with Docker-in-Docker.

- Category: DevOps & CI/CD
- Difficulty: intermediate
- Components: buildkite-agent, docker-dind, registry
- Tags: buildkite, ci, agents, dind
- Source: https://docker.recipes/devops/buildkite-agent-stack

## Overview

Buildkite Agent is a self-hosted build runner that connects to Buildkite's hosted platform to execute CI/CD pipelines. Originally developed by Buildkite as an alternative to fully cloud-hosted CI solutions, it allows organizations to run builds on their own infrastructure while leveraging Buildkite's powerful pipeline management interface. The agent polls for jobs from Buildkite's servers and executes them locally, providing complete control over the build environment while maintaining the convenience of a managed CI/CD platform.

This stack combines Buildkite Agent with Docker-in-Docker (DinD) to create an isolated containerized CI environment capable of building Docker images and running container-based workloads. The Docker daemon runs in a separate privileged container, while Buildkite agents connect to it via TCP, enabling secure Docker operations without exposing the host's Docker socket. A local Docker registry completes the stack, providing immediate storage for built images during multi-stage builds or testing scenarios.

Development teams and DevOps engineers who need to run Docker-based builds in Buildkite will find this configuration particularly valuable. Unlike cloud-hosted CI runners with limited customization, this self-hosted approach provides full control over the build environment, custom tooling installation, and network access while maintaining isolation between builds through containerization.

## Features

- Buildkite Agent with automatic job polling and pipeline execution
- Isolated Docker-in-Docker daemon with TLS certificate authentication
- Local Docker registry for immediate image storage and caching
- Privileged DinD container enabling full Docker functionality including volume mounts
- Agent auto-registration with configurable names and metadata
- Shared certificate volume for secure agent-to-daemon communication
- Horizontal scaling through additional agent containers
- Build artifact persistence through dedicated Docker volumes

## Use cases

- Running Docker image builds and multi-stage builds in Buildkite pipelines
- Testing containerized applications with full Docker Compose support
- Creating CI environments for teams migrating from Jenkins to Buildkite
- Executing integration tests requiring Docker containers and networking
- Building and pushing images to private registries from Buildkite jobs
- Running security scans and vulnerability assessments on Docker images
- Supporting development teams needing custom build tools and environments

## Prerequisites

- Buildkite organization with agent registration token
- Docker host with at least 4GB RAM for DinD operations
- Available port 5000 for local Docker registry access
- Privileged container support on the Docker host
- Network connectivity to api.buildkite.com for agent communication
- Understanding of Buildkite pipeline YAML configuration

## docker-compose.yml

```yaml
services:
  dind:
    image: docker:24-dind
    container_name: buildkite-dind
    restart: unless-stopped
    privileged: true
    environment:
      - DOCKER_TLS_CERTDIR=/certs
    volumes:
      - dind_certs:/certs
      - dind_data:/var/lib/docker

  agent-1:
    image: buildkite/agent:latest
    container_name: buildkite-agent-1
    restart: unless-stopped
    environment:
      - BUILDKITE_AGENT_TOKEN=${AGENT_TOKEN}
      - BUILDKITE_AGENT_NAME=agent-1
      - DOCKER_HOST=tcp://dind:2376
    volumes:
      - dind_certs:/certs/client:ro
    depends_on:
      - dind

  registry:
    image: registry:2
    container_name: buildkite-registry
    restart: unless-stopped
    ports:
      - "${REGISTRY_PORT:-5000}:5000"
    volumes:
      - registry_data:/var/lib/registry

volumes:
  dind_certs:
  dind_data:
  registry_data:
```

## .env

```bash
# Buildkite Agents
AGENT_TOKEN=your_buildkite_agent_token
REGISTRY_PORT=5000
```

## Usage notes

- Get agent token from Buildkite
- Agents auto-register
- Local registry at localhost:5000
- Scale by adding more agents

## Troubleshooting

- Agent shows 'connection refused' errors: Verify BUILDKITE_AGENT_TOKEN is valid and network allows HTTPS to api.buildkite.com
- Docker commands fail with 'Cannot connect to Docker daemon': Check dind container is running and DOCKER_HOST points to tcp://dind:2376
- Permission denied accessing /certs directory: Ensure dind_certs volume is properly mounted and containers have started in correct order
- Registry push fails with 'server gave HTTP response to HTTPS client': Configure Docker daemon in DinD with --insecure-registry flag for local registry
- Agent not appearing in Buildkite dashboard: Verify agent token permissions and check agent container logs for registration errors

