Configuration

Configuration for Boilermaker is done is one of 4 places:

1. The boilermaker.toml file in the template directory, which controls the behavior of that specific template.
2. An imported file, which can be used to override any configuration options declared in the boilermaker.toml file.
3. The command line, when running the boil new command, which can be used to override any configuration options declared in files.
4. The global ~/.boilermaker/boilermaker.toml file, which controls Boilermaker's behavior.

Template Configuration

The boilermaker.toml at the root of the template repository is the baseline configuration for a template. It has the following structure:

Basic Variables

[project]
VAR = VALUE
...

[variables]
VAR = VALUE
...

An example from the official Hello World template is as follows:

[project]
name = "boil-hello-world"
description = "Simple Hello World with Boilermaker"
version = "0.1.0"
default_lang = "bash"
repository = "https://github.com/yeajustmars/boil-hello-world"
authors = ["yeajustmars"]
keywords = ["boilermaker", "example", "hello-world"]
website = "https://github.com/yeajustmars/boil-hello-world"
license = "MIT"

[variables]
welcome_message = "Hello, World!"

• You can have as many variables as you want in the [variables] section and what they are named is entirely up to you.
• However, the variables in the [project] section are reserved keys for Boilermaker's internal use.

It's important to note that any valid TOML is supported, including nested values. The following is perfectly valid:

[project]
name = "boil-hello-world"
description = "Simple Hello World with Boilermaker"
version = "0.1.0"
default_lang = "bash"
repository = "https://github.com/yeajustmars/boil-hello-world"
authors = ["yeajustmars"]
keywords = ["boilermaker", "example", "hello-world"]
website = "https://github.com/yeajustmars/boil-hello-world"
license = "MIT"

[variables]
welcome_message = "Hello, World!"
my_nested_var = {
    a = 1
    b = true
    c = ["x", "y", "z"]
}

The variables can then be used in your template files using standard minijinja syntax. For instance, given the example above, you could interpolate these variables as follows:

<h1>{{ welcome_message }}</h1>
<!--  is "Hello, World!" -->

<p>My nested variable: {{ my_nested_var.c[0] }}</p>
<!-- is "x" -->

Remember: we're using HTML as the template language here but Boilermaker is language-agnostic. This same syntax would work in a Python file, a BASH script or a Dockerfile. Anything!

Variable Profiles

Variable profiles are a way to group variables together for different use cases. For instance, you might have a set of variables that are only relevant for a specific language or framework. You can declare these variable profiles in your boilermaker.toml file as follows:

[variables]
welcome_message = "Hello, World!"
other_var = "This is a variable that is always available."

[variables.profile.python]
welcome_message = "Override, Python World!"

[variables.profile.rust]
welcome_message = "Override, Rusty World!"

• When running boil new, you can specify which profile to use with the --profile (or just -p) flag. For instance, if you wanted to use the Python profile, you would run the following command:

boil new my-template --profile python

NOTE: variable profiles only work for the [variables] section of the boilermaker.toml file. The [project] section is not affected. This is to ensure that a single template has a single project configuration.

Extra Configuration Files

NOTE: feature coming soon in RC1

Command Line Configuration

Command line configuration is done by passing --var (or just -v) arguments to the boil new command. This allows you to override any configuration options declared in the boilermaker.toml file or imported files.

For instance, if you have this in your boilermaker.toml file:

[variables]
app_name = "my-app"

You can override the app_name variable by running the following command:

boil new my-template --var app_name=awesome-app

Global System Configuration

NOTE: feature coming soon in RC1