Cheat sheet
#
Skeleton configuration file#
Container basics#
Define a containerReference: containers
#
Set the default command to run in a containerReference: command
#
Set the default working directory for a containerReference: working_directory
#
Set an environment variable for a containerReference: environment
#
Mount a file or directory into a containerMount the project directory into the container at /code
:
Reference: volumes
#
Docker images#
Use an existing Docker image for a containerReference: image
#
Build a local Dockerfile to use as the image for a containerUse the Dockerfile from the images/my-container
directory:
Reference: build_directory
#
Pass a build arg to a DockerfileReference: build_args
#
Use a custom Dockerfile file nameUse the file AnotherDockerfile
from the images/my-container
directory:
Reference: dockerfile
#
Task basics#
Define a taskReference: tasks
#
Override the command for the task containerReference: command
#
Override the working directory for the task containerReference: working_directory
#
Set an environment variable for the task containerReference: environment
#
Expose additional ports on the task containerReference: 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:
To specify that a container must start before the main task container for a single task:
Reference: container: dependencies
, task: dependencies
#
Wait for a container to be ready to accept requests before starting containers that depend on itBatect will automatically use a health check defined in the container's image's Dockerfile:
Alternatively, specify the health check settings on the container:
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 itReference: setup_commands
#
Customise the environment variables of a dependency containerWhen 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 containerWhen 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 containerWhen 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)Reference: prerequisites
#
Caching#
Cache a directory between task invocations#
Clean all caches for the current projectReference: --clean
#
CI#
Use directories for caches instead of volumesUse the --cache-type=directory
option, or set the BATECT_CACHE_TYPE
environment variable to directory
:
Reference: --cache-type
#
Avoiding port conflictsReference: --disable-ports
#
Config variables#
Defining a config variableReference: config_variables
#
Referencing a config variableUse an expression like <{log_level}
on supported properties.
#
Overriding a config variable on the command lineReference: --config-var
#
Overriding a config variable with a fileCreate a YAML file in variable_name: value
format, for example:
Then use --config-vars-file
to tell Batect to use that file:
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 machineUse an expression like $MY_ENVIRONMENT_VARIABLE
on supported properties.
#
Defining and using a config variableThen use an expression like <{log_level}
on supported properties.
Reference: config_variables
#
Debugging#
See output from all containers when running a taskUse --output=all
:
This produces output similar to the following:
Reference: --output
#
Disable cleanup of containers when a task finishesUse --no-cleanup
, --no-cleanup-after-failure
or --no-cleanup-after-success
:
Reference: --no-cleanup
, --no-cleanup-after-failure
and --no-cleanup-after-success
#
Docker#
Access the host machine's Docker daemon from within a containerMount the Docker daemon socket into the container, and then use the docker
CLI tool like normal:
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 settingsUse --docker-host
(or set the DOCKER_HOST
environment variable):
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 filesIf /my-project/a.yml
contains:
And /my-project/includes/b.yml
contains:
Then the resulting configuration is as if /my-project/a.yml
was:
Reference: include
#
Reference a bundleReference: include
#
Networking#
Expose a port to the host machineThis makes port 5678 on the container accessible at port 1234 on the host machine:
Reference: ports
#
Expose a port to other containers in the taskThere 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 containerThis allows other containers to reference my-container
by using other-name
:
Reference: additional_hostnames
/etc/hosts
#
Add extra hostnames to To configure processes inside my-container
to resolve database.example.com
to 1.2.3.4
:
Reference: additional_hosts
#
Otherroot
#
Avoiding build artefacts being owned by Reference: run_as_current_user