Skip to main content

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: warninghost: 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:

Loading...

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