Docker Run

Run a Docker container with full control over image, commands, volumes, ports, resources, and GPU access.

---

Plugin: docker-run Group: Infrastructure

Task Type
dev.bringup.plugin.docker.run

---

Examples

Basic container execution

id: docker-hello
namespace: examples
description: Run a command inside a Docker container

tasks:
  - id: run-ubuntu
    type: dev.bringup.plugin.docker.run
    containerImage: ubuntu:22.04
    commands:
      - echo "Hello from Docker!"
      - cat /etc/os-release

With environment variables and volumes

id: docker-data-processing
namespace: analytics
description: Process data using a custom Docker image

inputs:
  - id: dataset_path
    type: STRING
    defaults: /mnt/datasets/raw

tasks:
  - id: process
    type: dev.bringup.plugin.docker.run
    containerImage: myregistry.io/data-processor:latest
    commands:
      - python process.py --input /data --output /results
    env:
      DATASET_PATH: "{{ inputs.dataset_path }}"
      LOG_LEVEL: INFO
    volumes:
      - hostPath: "{{ inputs.dataset_path }}"
        path: /data
      - hostPath: ./output
        path: /results
    wait: true

With resource limits

tasks:
  - id: limited-container
    type: dev.bringup.plugin.docker.run
    containerImage: heavy-compute:v2
    commands:
      - ./run-benchmark.sh
    cpu: "4"
    memory: "8g"
    privileged: false

With GPU access

id: ml-inference
namespace: ml
description: Run ML inference with GPU support

tasks:
  - id: inference
    type: dev.bringup.plugin.docker.run
    containerImage: nvidia/cuda:12.0-runtime-ubuntu22.04
    commands:
      - nvidia-smi
      - python inference.py --model /models/latest
    deviceRequests:
      - capabilities:
          - gpu
        count: 1
    volumes:
      - hostPath: /shared/models
        path: /models
    env:
      CUDA_VISIBLE_DEVICES: "0"

With port bindings

tasks:
  - id: web-service
    type: dev.bringup.plugin.docker.run
    containerImage: nginx:alpine
    portBindings:
      - hostPort: 8080
        containerPort: 80
    wait: false

Pull policy configuration

tasks:
  - id: always-pull
    type: dev.bringup.plugin.docker.run
    containerImage: myregistry.io/app:latest
    pullPolicy: ALWAYS
    commands:
      - ./start.sh

Complete example with all features

id: full-docker-flow
namespace: production
description: Full-featured Docker task demonstration

inputs:
  - id: image_tag
    type: STRING
    defaults: latest
  - id: gpu_count
    type: INT
    defaults: 1
  - id: enable_debug
    type: BOOLEAN
    defaults: false

variables:
  REGISTRY: myregistry.io

tasks:
  - id: run-pipeline
    type: dev.bringup.plugin.docker.run
    containerImage: "{{ variables.REGISTRY }}/ml-pipeline:{{ inputs.image_tag }}"
    commands:
      - echo "Starting pipeline..."
      - python -m pipeline.run --stage all
      - echo "Pipeline complete"
    env:
      DEBUG: "{{ inputs.enable_debug }}"
      PYTHONUNBUFFERED: "1"
    volumes:
      - hostPath: /shared/data
        path: /data
      - hostPath: /shared/models
        path: /models
        readOnly: true
    deviceRequests:
      - capabilities:
          - gpu
        count: "{{ inputs.gpu_count }}"
    cpu: "8"
    memory: "32g"
    privileged: false
    pullPolicy: IF_NOT_PRESENT
    wait: true
    timeout: "3600s"
    retry:
      type: exponential
      max_attempt: 3
      interval: "30s"
      max_interval: "300s"
      delay_factor: 2.0

---

Properties

containerImage (Required)

Type	string
Required	Yes
Description	Docker image to run. Supports full registry paths and tags (e.g., ubuntu:22.04, myregistry.io/app:v1.2). Template variables are supported.

commands

Type	List[string]
Required	No
Default	[]
Description	Commands to execute inside the container. Joined with newlines and passed to /bin/sh -lc.

env

Type	Dict[string, string]
Required	No
Default	{}
Description	Environment variables to set inside the container. Each entry becomes a -e KEY=VALUE flag. Template variables are supported in values.

volumes

Type	List[VolumeBinding]
Required	No
Default	[]
Description	Volume mount bindings. Each entry maps a host path to a container path.

VolumeBinding:

Property	Type	Required	Description
hostPath	string	Yes	Path on the host machine
path	string	Yes	Mount path inside the container
readOnly	boolean	No	Mount as read-only (default: false)

portBindings

Type	List[PortBinding]
Required	No
Default	[]
Description	Port mappings between host and container.

PortBinding:

Property	Type	Required	Description
hostPort	integer	Yes	Port on the host
containerPort	integer	Yes	Port inside the container

cpu

Type	string
Required	No
Default	No limit
Description	CPU limit for the container (e.g., "2", "0.5"). Maps to Docker's --cpus flag.

memory

Type	string
Required	No
Default	No limit
Description	Memory limit for the container (e.g., "512m", "4g"). Maps to Docker's --memory flag.

privileged

Type	boolean
Required	No
Default	false
Description	Run the container in privileged mode. Use with caution as this grants full host access.

pullPolicy

Type	string
Required	No
Default	"IF_NOT_PRESENT"
Possible Values	ALWAYS, NEVER, IF_NOT_PRESENT
Description	When to pull the Docker image. ALWAYS pulls every time, NEVER uses only local images, IF_NOT_PRESENT pulls only if the image is missing locally.

wait

Type	boolean
Required	No
Default	true
Description	Whether to wait for the container to complete before proceeding. Set to false for long-running services.

deviceRequests

Type	List[DeviceRequest]
Required	No
Default	[]
Description	Device requests (e.g., GPU access).

DeviceRequest:

Property	Type	Required	Description
capabilities	List[string]	Yes	Device capabilities (e.g., ["gpu"])
count	integer	No	Number of devices to request

---

Common Task Properties

See Shell > Common Task Properties for id, type, description, disabled, timeout, retry, allow_failure, run_if, and worker_group.

---

Notes

• The container's working directory is automatically set to the workspace ($PWD), and the workspace is mounted as a volume.
• The --rm flag is always added to clean up the container after execution.
• GPU access requires the NVIDIA Container Toolkit to be installed on the worker node.
• Template variables in containerImage and env values are resolved before execution.
• Incompatible configurations (e.g., privileged: true with deviceRequests) will produce validation warnings.