1. Resources
  2. /
  3. Plugins
  4. /
  5. docker-service-buildkite-plugin

Docker Service Buildkite plugin

A Buildkite plugin for running a container alongside your build step. For example to ensure that a local Postgres instance is available in the step that runs your database backend integration tests.

Quickstart

The following step definition will spin up a PostgreSQL container with some default settings. The container will be bound to both the localhost and external network interface of the machine running the build. It will then run the integration-tests.sh script after which the container is spun down.

steps:
  - label: integration-tests
    command: ./integration-tests.sh
    plugins:
      - improbable-eng/docker-service#v0.3.0:
          container: postgres:12.6
          flags:
            - --env=POSTGRES_DB=postgres
            - --env=POSTGRES_USER=postgres
            - --env=POSTGRES_PASSWORD=postgres

Advanced usage

Service logs

Any logs generated by the service container over the course of the build will be dumped at the end into the docker-service.logs file. They can then be uploaded as part of the artifacts of your step for later inspection.

Specifying a custom command

You can also specify a specific command to run inside the docker container:

steps:
  - label: my-step
    command: ./step-script.sh
    plugins:
      - improbable-eng/docker-service#v0.3.0:
          container: a-container:1.2.3
          cmd: "my-command --flag=value arg1 arg1"

Multi-build network setup

If you have multiple builds running on the same machine they can end up requiring running the same service via the Docker Service plugin. This creates conflicts when those services try to bind to the same host port.

To address this issue use the network option. The plugin will attach the container running your service to the specified docker network. It the network does not yet exist it will be created. The IP of the container running the service will be available to your build via the DOCKER_SERVICE_IP environment variable.

This information can then be used to attach another docker container to the same network and use the service. This would typically require your build step to also run in a docker container, for example by using the Docker Buildkite plugin with its network option.

steps:
  - label: my-dockerised-step
    plugins:
      - improbable-eng/docker-service#v0.3.0:
          container: postgres:12.6
          network: "postgres"
          flags:
            - --env=POSTGRES_DB=postgres
            - --env=POSTGRES_USER=postgres
            - --env=POSTGRES_PASSWORD=postgres
      - buildkite-plugins/docker#v3.8.0:
          container: "my-build-container:v1.0.0"
          command: "./my-db-test-script.sh"
          network: "postgres"
          propagate-uid-gid: true
          environment:
            - DOCKER_SERVICE_IP

Configuration

OptionRequiredTypeDescriptionDefault
containerYesstringContainer image to runn.a
cmdNostringCommand to run in the container<empty string>
flagsNolist of stringsList of flags for ‘docker run’<empty list>
networkNostringDocker network to which to attach the containerhost

Environment variables

The plugin will set the following environment variables which will be accessible to your build:

Environment VariableDescription
DOCKER_SERVICE_CONTAINER_IDDocker ID of the container running the service.
DOCKER_SERVICE_IPIP at which the service can be reached.

The plugins listed on this webpage are provided for informational purposes only. They have not undergone any formal security review or assessment. While we strive to provide useful resources, we cannot guarantee the safety, reliability, or integrity of these plugins. Users are strongly advised to conduct their own security evaluations before downloading, installing, or using any plugin. By using these plugins, you acknowledge and accept any risks associated with their use. We disclaim any liability for any harm or damages arising from the use of the plugins listed.

Start turning complexity into an advantage

Create an account to get started with a 30-day free trial. No credit card required.

Buildkite Pipelines

Platform

  1. Pipelines
  2. Pipeline templates
  3. Public pipelines
  4. Test Engine
  5. Package Registries
  6. Mobile Delivery Cloud
  7. Pricing

Hosting options

  1. Self-hosted agents
  2. Mac hosted agents
  3. Linux hosted agents

Resources

  1. Docs
  2. Blog
  3. Changelog
  4. Webinars
  5. Plugins
  6. Case studies
  7. Events
  8. Migration Services
  9. Comparisons

Company

  1. About
  2. Careers
  3. Press
  4. Brand assets
  5. Contact

Solutions

  1. Replace Jenkins
  2. Workflows for AI/ML
  3. Testing at scale
  4. Monorepo mojo
  5. Bazel orchestration

Legal

  1. Terms of Service
  2. Acceptable Use Policy
  3. Privacy Policy
  4. Subprocessors
  5. Service Level Agreement

Support

  1. System status
  2. Forum
© Buildkite Pty Ltd 2025