Cheat sheet

Skeleton configuration file#

batect.yml

containers:
  my-container:
    image: alpine:3.11.3

tasks:
  say-hello:
    description: Say hello to the nice person reading the Batect documentation
    run:
      container: my-container
      command: echo 'Hello world!'

Container basics#

Define a container#

batect.yml

containers:
  my-container:
    image: alpine:3.11.3
    command: echo "Hello world"

Reference: containers

Set the default command to run in a container#

batect.yml

containers:
  my-container:
    # ...other config
    command: echo "Hello world"

Reference: command

Set the default working directory for a container#

batect.yml

containers:
  my-container:
    # ...other config
    working_directory: /my/working/dir

Reference: working_directory

Set an environment variable for a container#

batect.yml

containers:
  my-container:
    # ...other config
    environment:
      MY_ENVIRONMENT_VARIABLE: "the value"

Reference: environment

Mount a file or directory into a container#

Mount the project directory into the container at /code:

batect.yml

containers:
  my-container:
    # ...other config
    volumes:
      - local: .
        container: /code

Reference: volumes

Docker images#

Use an existing Docker image for a container#

batect.yml

containers:
  my-container:
    image: alpine:3.11.3

Reference: image

Build a local Dockerfile to use as the image for a container#

Use the Dockerfile from the images/my-container directory:

batect.yml

containers:
  my-container:
    build_directory: images/my-container

Reference: build_directory

Pass a build arg to a Dockerfile#

batect.yml

containers:
  my-container:
    build_directory: images/my-container
    build_args:
      MY_BUILD_ARG: "some value"

Reference: build_args

Use a custom Dockerfile file name#

Use the file AnotherDockerfile from the images/my-container directory:

batect.yml

containers:
  my-container:
    build_directory: images/my-container
    dockerfile: AnotherDockerfile

Reference: dockerfile

Task basics#

Define a task#

batect.yml

tasks:
  my-task:
    run:
      container: my-container

Reference: tasks

Override the command for the task container#

batect.yml

tasks:
  my-task:
    run:
      container: my-container
      command: echo 'Hello there!'

Reference: command

Override the working directory for the task container#

batect.yml

tasks:
  my-task:
    run:
      container: my-container
      working_directory: /some/other/directory

Reference: working_directory

Set an environment variable for the task container#

batect.yml

tasks:
  my-task:
    run:
      container: my-container
      environment:
        MY_ENVIRONMENT_VARIABLE: "the value"

Reference: environment

Expose additional ports on the task container#

batect.yml

tasks:
  my-task:
    run:
      container: my-container
      ports:
        - local: 8080
          container: 8080

Reference: ports

Task lifecycle#

Dependencies#

Require one container to start before another (create a dependency)#

This can be configured in two ways: on the container, or on a per-task basis.

To specify that a container must always start before another container:

batect.yml

containers:
  my-container:
    # ...other config
    dependencies:
      - other-container

To specify that a container must start before the main task container for a single task:

batect.yml

tasks:
  my-task:
    run:
      container: my-container
    dependencies:
      - other-container

Reference: container: dependencies, task: dependencies

Wait for a container to be ready to accept requests before starting containers that depend on it#

Batect will automatically use a health check defined in the container's image's Dockerfile:

Dockerfile

FROM my-image:1.2.3

HEALTHCHECK --interval=2s --retries=10 CMD /tools/health-check.sh

Alternatively, specify the health check settings on the container:

batect.yml

containers:
  my-container:
    # ...other config
    health_check:
      command: /tools/health-check.sh
      retries: 10
      interval: 2s

The command must exit with a non-zero exit code when the container is not ready, and exit with a zero exit code when the container is ready.

Reference: HEALTHCHECK, health_check

Run a command in a container before starting containers that depend on it#

batect.yml

containers:
  my-container:
    # ...other config
    setup_commands:
      - command: /tools/setup.sh

Reference: setup_commands

Customise the environment variables of a dependency container#

batect.yml

tasks:
  my-task:
    dependencies:
      - other-container
    run:
      container: my-container
    customise:
      other-container:
        environment:
          OVERRIDDEN_VAR: overridden value from task
          NEW_VAR: new value from task

containers:
  main-container:
    image: ...

  other-container:
    image: ...
    environment:
      CONTAINER_VAR: set on container
      OVERRIDDEN_VAR: won't be used

When the task my-task is run, other-container will start with the environment variables:

CONTAINER_VAR: set on container
OVERRIDDEN_VAR: overridden value from task
NEW_VAR: new value from task

Reference: customise

Expose additional ports on a dependency container#

batect.yml

tasks:
  my-task:
    dependencies:
      - other-container
    run:
      container: my-container
    customise:
      other-container:
        ports:
          - 3000:4000

containers:
  main-container:
    image: ...

  other-container:
    image: ...
    ports:
      - 1000:2000

When the task my-task is run, other-container will start with container ports 2000 and 4000 exposed as ports 1000 and 3000 on the host machine.

Reference: customise

Customise the working directory of a dependency container#

batect.yml

tasks:
  my-task:
    dependencies:
      - other-container
    run:
      container: my-container
    customise:
      other-container:
        working_directory: /customised

containers:
  main-container:
    image: ...

  other-container:
    image: ...
    working_directory: /wont-be-used

When the task my-task is run, other-container will in /customised.

Reference: customise

Require one task to run to completion before another (create a prerequisite)#

batect.yml

tasks:
  my-task:
    prerequisites:
      - my-other-task
    run:
      container: my-container

  my-other-task:
    # ...config for task

Reference: prerequisites

Caching#

Cache a directory between task invocations#

batect.yml

containers:
  my-container:
    # ...other config
    volumes:
      - type: cache
        name: my_cache
        container: /caches/my_cache

Reference: volumes and caches

Clean all caches for the current project#

./batect --clean

Reference: --clean

CI#

Use directories for caches instead of volumes#

Use the --cache-type=directory option, or set the BATECT_CACHE_TYPE environment variable to directory:

./batect --cache-type=directory my-task

Reference: --cache-type

Avoiding port conflicts#

./batect --disable-ports my-task

Reference: --disable-ports

Config variables#

Defining a config variable#

config_variables:
  log_level:
    description: Log level to use for application
    default: debug

Reference: config_variables

Referencing a config variable#

Use an expression like <{log_level} on supported properties.

Overriding a config variable on the command line#

./batect --config-var log_level=warning my-task

Reference: --config-var

Overriding a config variable with a file#

Create a YAML file in variable_name: value format, for example:

my-vars.yml

log_level: warning
host: myawesomeapp.com

Then use --config-vars-file to tell Batect to use that file:

./batect --config-vars-file=my-vars.yml my-task

Batect will automatically use config variables from a file called batect.local.yml if it exists and --config-vars-file is not specified.

Reference: --config-vars-file

Configurability#

Use an environment variable from the host machine#

Use an expression like $MY_ENVIRONMENT_VARIABLE on supported properties.

Defining and using a config variable#

config_variables:
  log_level:
    description: Log level to use for application
    default: debug

Then use an expression like <{log_level} on supported properties.

Reference: config_variables

Debugging#

See output from all containers when running a task#

Use --output=all:

./batect --output=all my-task

This produces output similar to the following:

Reference: --output

Disable cleanup of containers when a task finishes#

Use --no-cleanup, --no-cleanup-after-failure or --no-cleanup-after-success:

./batect --no-cleanup my-task

Reference: --no-cleanup, --no-cleanup-after-failure and --no-cleanup-after-success

Docker#

Access the host machine's Docker daemon from within a container#

Mount the Docker daemon socket into the container, and then use the docker CLI tool like normal:

batect.yml

containers:
  docker-env:
    volumes:
      - local: /var/run/docker.sock
        container: /var/run/docker.sock

Note that local settings like registry credentials will not be forwarded to the container - the container will need to be configured with these.

Connect to a Docker daemon using non-default connection settings#

Use --docker-host (or set the DOCKER_HOST environment variable):

./batect --docker-host=unix:///var/run/other-docker.sock

This option accepts Unix sockets (on macOS and Linux), named pipes (on Windows) and TCP addresses (on all platforms).

Reference: --docker-host

Includes and bundles#

Split a configuration file into multiple files#

If /my-project/a.yml contains:

/my-project/a.yml

containers:
  my-container:
    image: my-image:1.2.3

include:
  - includes/b.yml

And /my-project/includes/b.yml contains:

/my-project/includes/b.yml

tasks:
  my-task:
    run:
      container: my-container

Then the resulting configuration is as if /my-project/a.yml was:

containers:
  my-container:
    image: my-image:1.2.3

tasks:
  my-task:
    run:
      container: my-container

Reference: include

Reference a bundle#

include:
  - type: git
    repo: https://github.com/batect/hello-world-bundle.git
    ref: 0.2.0

Reference: include

Networking#

Expose a port to the host machine#

This makes port 5678 on the container accessible at port 1234 on the host machine:

batect.yml

containers:
  my-container:
    # ...other config
    ports:
      - local: 1234
        container: 5678

Reference: ports

Expose a port to other containers in the task#

There is no configuration required to expose a port from a container to another container running in the same task.

Use the name of the container as its hostname. For example, to make a HTTP request to port 8080 on my-container from another container, use http://my-container:8080.

Add another hostname to a container#

This allows other containers to reference my-container by using other-name:

batect.yml

containers:
  my-container:
    # ...other config
    additional_hostnames:
      - other-name

Reference: additional_hostnames

Add extra hostnames to `/etc/hosts`#

To configure processes inside my-container to resolve database.example.com to 1.2.3.4:

batect.yml

containers:
  my-container:
    # ...other config
    additional_hosts:
      database.example.com: 1.2.3.4

Reference: additional_hosts

Other#

Avoiding build artefacts being owned by `root`#

Use run as current user mode:

batect.yml

containers:
  my-container:
    # ...other config
    run_as_current_user:
      enabled: true
      home_directory: /home/container-user

Reference: run_as_current_user

Skeleton configuration file#

Container basics#

Define a container#

Set the default command to run in a container#

Set the default working directory for a container#

Set an environment variable for a container#

Mount a file or directory into a container#

Docker images#

Use an existing Docker image for a container#

Build a local Dockerfile to use as the image for a container#

Pass a build arg to a Dockerfile#

Use a custom Dockerfile file name#

Task basics#

Define a task#

Override the command for the task container#

Override the working directory for the task container#

Set an environment variable for the task container#

Expose additional ports on the task container#

Task lifecycle#

Dependencies#

Require one container to start before another (create a dependency)#

Wait for a container to be ready to accept requests before starting containers that depend on it#

Run a command in a container before starting containers that depend on it#

Customise the environment variables of a dependency container#

Expose additional ports on a dependency container#

Customise the working directory of a dependency container#

Require one task to run to completion before another (create a prerequisite)#

Caching#

Cache a directory between task invocations#

Clean all caches for the current project#

CI#

Use directories for caches instead of volumes#

Avoiding port conflicts#

Config variables#

Defining a config variable#

Referencing a config variable#

Overriding a config variable on the command line#

Overriding a config variable with a file#

Configurability#

Use an environment variable from the host machine#

Defining and using a config variable#

Debugging#

See output from all containers when running a task#

Disable cleanup of containers when a task finishes#

Docker#

Access the host machine's Docker daemon from within a container#

Connect to a Docker daemon using non-default connection settings#

Includes and bundles#

Split a configuration file into multiple files#

Reference a bundle#

Networking#

Expose a port to the host machine#

Expose a port to other containers in the task#

Add another hostname to a container#

Add extra hostnames to /etc/hosts#

Other#

Avoiding build artefacts being owned by root#

Add extra hostnames to `/etc/hosts`#

Avoiding build artefacts being owned by `root`#