Config Reference

Every section in a dobi.yaml configuration file defines a resource (with the exception of meta, which is configuration for dobi).

Each section in the file has the following form:

type=name:
    field: value
    ...

Each resource must be one of the following resource types:

image

An image resource provides actions for working with a Docker image. If an image is buildable it is considered up-to-date if all files in the build context have a modified time older than the created time of the image. If using inline Dockerfile, the dobi.yaml file will be considered as a part of the build context.

Example

An image with build args:

image=project-dev:
    image: myproject-dev
    context: .
    args:
      version: '3.1.4'
      url: http://example.com/foo

image (required)

type:string

The name of the image without a tag. Tags must be specified in the tags field. This field supports Config Variables.

dockerfile

type:string

The path to the Dockerfile used to build the image. This path is relative to context. Can not be used with steps

steps

type:string

An inline Dockerfile used to build the image. steps can not be used with the dockerfile field.

context

type:string default:.

The build context used to build the image.

args

type:mapping key: value

Build args used to build the image. Values in the mapping support Config Variables.

target

type:string

The target stage to build in a multi-stage Dockerfile. Defaults to the last stage.

pull-base-image-on-build

type:bool

If true the base image used in the Dockerfile will be pulled before building the image.

pull

type:string default:always

Pull an image instead of building it. The value may be one of: * once - only pull if the image:tag does not exist * always - always pull the image * never - don’t pull or build the image. Use one that is already present locally * <duration> - pull if the image hasn’t been pulled in at least duration. The format of duration is a number followed by a single character time unit (ex: 40s, 2h, 30min)

tags

type:list of tags default:['{unique}']

The image tags applied to the image before pushing the image to a registry. The first tag in the list is used when the image is built. Each item in the list supports Config Variables.

network-mode

type:string

The network mode to use for each step in the Dockerfile.

cache-from

type:

A list of images to use as the cache for a build.

depends

type:list of tasks

The list of task dependencies.

description

type:string

of a resource Deprecated use Annotations.Description

annotations

type:AnnotationFields

job

A job resource uses an image to run a job in a container.

A job resource that doesn’t have an artifact is never considered up-to-date and will always run. If a job resource has an artifact the job will be skipped if the artifact is newer than the source. The last modified time of the artifact files is compared against the last modified time of the files in sources, or if sources is left unset, the last modified time of the use image and all the files in the mounts.

mounts are provided to the container as bind mounts. If the DOBI_NO_BIND_MOUNT environment variable, or –no-build-mount flag is set, then mounts will be copied into the container, and all artifacts will be copied out of the container to the host after the job is complete.

The image specified in use and any mount resources listed in mounts are automatically added as dependencies and will always be created first.

Example

Run a container using the builder image to compile some source code to ./dist/app-binary.

job=compile:
    use: builder
    mounts: [source, dist]
    artifact: dist/app-binary

use (required)

type:string

The name of an image resource. The referenced image is used to created the container for the job.

artifact

type:list of file paths or glob patterns

File paths or globs identifying the files created by the job. Paths to directories must end with a path separator (/). Paths are relative to the dobi.yaml

command

type:shell quoted string

The command to run in the container.

"bash -c 'echo something'"

entrypoint

type:shell quoted string

Override the image entrypoint

sources

type:list of file paths or glob patterns

File paths or globs of the files used to create the artifact. The modified time of these files are compared to the modified time of the artifact to determine if the job is stale. If the sources list is defined the modified time of mounts and the use image are ignored.

mounts

type:list of mount resources

A list of mount resources to use when creating the container.

privileged

type:bool

Gives extended privileges to the container

interactive

type:bool

Makes the container interative and enables a tty.

env

type:list of key=value strings

Environment variables to pass to the container. This field supports Config Variables.

provide-docker

type:bool

Exposes the docker engine to the container by either mounting the unix socket or setting the DOCKER_HOST environment variable. All environment variables with a DOCKER_ prefix in the environment are set on the container.

net-mode

type:string

The network mode to use. This field supports Config Variables.

working-dir

type:string

The directory to set as the active working directory in the container. This field supports Config Variables.

user

type:string

Username or UID to use in the container. Format user[:group].

ports

type:list of ‘host_port:container_port’

Publish ports to the host

devices

type:list of device specs

Maps the host devices you want to connect to a container

{Host: /dev/fb0, Container: /dev/fb0, Permissions: rwm}

labels

type:map of string keys to string values

sets the labels of the running job container

depends

type:list of tasks

The list of task dependencies.

description

type:string

of a resource Deprecated use Annotations.Description

annotations

type:AnnotationFields

mount

A mount resource creates a host bind mount or named volume mount.

Example

A mount named source that mounts the current host directory as /app/code in the container.

mount=source:
    bind: .
    path: /app/code

mount=named:
    name: app-data
    path: /data

bind

type:string

The host path to create and mount. This field supports expansion of ~ to the current users home directory.

path (required)

type:string

The container path of the mount

name

type:string

The name of a named volume

read-only

type:bool

Set the mount to be read-only

file

type:bool

When true create an empty file instead of a directory

mode

type:int default:0755 (for directories), 0644 (for files)

The file mode to set on the host file or directory when it is created.

description

type:string

of a resource Deprecated use Annotations.Description

annotations

type:AnnotationFields

alias

An alias resource is a list of other tasks which will be run in the order they are listed.

Example

An alias that runs three other tasks:

alias=test
    tasks: [test-unit, test-integration, test-acceptance]

tasks (required)

type:list of tasks

The list of tasks

description

type:string

of a resource Deprecated use Annotations.Description

annotations

type:AnnotationFields

compose

A compose resource runs docker-compose to create an isolated environment. The compose resource keeps containers running until dobi exits so the containers can be used by other tasks that depend on the compose resource, or are listed after it in an alias.

Note

Docker Compose must be installed and available in $PATH to use this resource.

Example

Start a Compose environment setting the project name to web-devenv and using two Compose files.

compose=devenv:
    files: [docker-compose.yml, docker-compose-dev.yml]
    project: 'web-devenv'

files

type:list of filenames

The Compose files to use. This field supports Config Variables.

project (required)

type:string

The project name used by Compose. This field supports Config Variables.

stop-grace

type:int default:5

Seconds to wait for containers to stop before killing them.

depends

type:list of tasks

The list of task dependencies.

description

type:string

of a resource Deprecated use Annotations.Description

annotations

type:AnnotationFields

env

An env resource provides environment variables to job and compose resources.

Example

Define some variables for a job

env=settings:
    files: [local.env]
    variables: [PORT=3838, HOST=stage]

files

type:list of filenames

List of files which contain environment variables

variables

type:list of environment variables

List of environment variable key=value pairs

description

type:string

of a resource Deprecated use Annotations.Description

annotations

type:AnnotationFields

meta

Configure dobi and include other config files.

Example

Set the the project name to mywebapp and run the all task by default.

meta:
    project: mywebapp
    default: all

default

type:string

The name of a task from the dobi.yml to run when no task name is specified on the command line.

project

type:string default:basename of ``dobi.yml``

The name of the project. Used to create unique identifiers for image tags and container names.

include

type:list of file paths or glob patterns

A list of dobi configuration files to include. Paths are relative to the current working directory. Includs can be partial configs that depend on resources in any of the other included files.

exec-id

type:string default:{user.name}

A template value used as part of unique identifiers for image tags and container names. This field supports Config Variables. This value can be overridden with the $DOBI_EXEC_ID environment variable.