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:

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

Edit this page