Overview
note
This page reflects the options available in the most recent version of Batect.
Batect uses a YAML-based configuration file.
By convention, this file is called batect.yml
and is placed in the root of your project (alongside the batect
script).
You can use a different name or location and tell batect
where to find it with the
--config-file
or -f
option.
The following is a sample "hello world" configuration file:
Run it with ./batect say-hello
:
Get a list of available tasks with ./batect --list-tasks
:
#
DefinitionConfiguration files are made up of the following fields:
project_name
#
The name of your project. Used to label any images built.
If a project name is not provided, the project name is taken from the directory containing the configuration file. For example, if your configuration
file is /home/alex/projects/my-cool-app/batect.yml
and you do not provide a project name, my-cool-app
will be used automatically.
Project names must be valid Docker references:
they must contain only:
- lowercase letters
- digits
- dashes (
-
) - single consecutive periods (
.
) - one or two consecutive underscores (
_
)
they must not start or end with dashes, periods or underscores
config_variables
#
Definitions for each of the config variables that are used throughout your configuration, in name: options
format.
Config variable names must start with a letter and contain only letters, digits, dashes (-
), periods (.
) and underscores (_
). They must not start with batect
.
Detailed reference for config_variables
containers
#
Definitions for each container, in name: options
format.
Container names must be valid Docker references:
they must contain only:
- lowercase letters
- digits
- dashes (
-
) - single consecutive periods (
.
) - one or two consecutive underscores (
_
)
they must not start or end with dashes, periods or underscores
Detailed reference for containers
include
#
List of configuration files or bundles to include in this project.
This is useful for breaking up a large project into smaller files, or for sharing configuration between projects.
Detailed reference for includes
tasks
#
Definitions for each task, in name: options
format.
Task names must meet the following requirements:
they must contain only:
- uppercase or lowercase letters
- digits
- dashes (
-
) - periods (
.
) - underscores (
_
) - colons (
:
)
they must start with a letter or digit
they must end with a letter or digit
#
ExpressionsSome fields support expressions - references to environment variables on the host or config variables.
Detailed reference for expressions
#
Anchors, aliases, extensions and mergingBatect supports YAML anchors and aliases. This allows you to specify a value in one place, and refer to it elsewhere. For example:
Anchors (&...
) must be defined before they are referenced with an alias (*...
).
Batect also supports extensions, which behave in an identical way, but allow you to define values before you use it for the first time. The following is equivalent to the example above:
Extensions must be defined at the root level of your configuration file, and the key must start
with a period (.
).
Batect also supports the merge operator (<<
) in maps. For example:
You can merge a single map with <<: *other-map
, or multiple maps with <<: [ *map-1, *map-2 ]
.
Local values take precedence over values merged into a map (regardless of the position of the <<
entry),
and values from sources earlier in the list of maps take precedence over values from later sources.
(For example, if both map-1
and map-2
define a value for PORT
in the example earlier, the
value in map-1
is used.)
#
ExamplesExamples are provided in the reference for config_variables
, containers
,
includes
and tasks
, as well as on the cheat sheet.
For further examples and real-world scenarios, take a look at the sample projects.