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

database              |                                                                                                                                                                                     database              | waiting for server to shut down....2019-09-14 10:14:29.060 UTC [83] LOG:  received fast shutdown request                                                                            database              | 2019-09-14 10:14:29.061 UTC [83] LOG:  aborting any active transactions                                                                                                             database              | 2019-09-14 10:14:29.064 UTC [83] LOG:  background worker "logical replication launcher" (PID 90) exited with exit code 1                                                            database              | 2019-09-14 10:14:29.064 UTC [85] LOG:  shutting down                                                                                                                                database              | 2019-09-14 10:14:29.085 UTC [83] LOG:  database system is shut down                                                                                                                 database              |  done                                                                                                                                                                               database              | server stopped                                                                                                                                                                      database              |                                                                                                                                                                                     database              | PostgreSQL init process complete; ready for start up.                                                                                                                               database              |                                                                                                                                                                                     database              | 2019-09-14 10:14:29.174 UTC [1] LOG:  listening on IPv4 address "0.0.0.0", port 5432                                                                                                database              | 2019-09-14 10:14:29.174 UTC [1] LOG:  listening on IPv6 address "::", port 5432                                                                                                     database              | 2019-09-14 10:14:29.177 UTC [1] LOG:  listening on Unix socket "/var/run/postgresql/.s.PGSQL.5432"                                                                                  database              | 2019-09-14 10:14:29.189 UTC [129] LOG:  database system was shut down at 2019-09-14 10:14:29 UTC                                                                                    database              | 2019-09-14 10:14:29.194 UTC [1] LOG:  database system is ready to accept connections                                                                                                exchange-rate-service | info: [http:6000 exchange-rate-service] ::ffff:127.0.0.1:57532 => GET /ping                                                                                                         database              | Container became healthy.                                                                                                                                                           build-env             | Running bundle exec rake spec:integration...
00:00-00:09

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

Subscribe to the Batect newsletter

Get news and announcements direct to your inbox.