Boilerplates CLI v0.2.0 is here, and this update changes the foundation of how templates are structured, rendered, and generated.
The short version: Boilerplates is no longer just one repository with everything in one place. The CLI app and the template library are now split, templates use the new template.json runtime, template files live in a dedicated files/ directory, and the generator now supports remote generation over SSH.
If you already used Boilerplates for Docker Compose templates, this is the update to pay attention to.
Repositories#
Boilerplates is now split into two separate projects:
The CLI is the app you install and run. The library is where the actual templates live.
This makes the project easier to maintain because the runtime and the template content can evolve separately. It also makes it clearer where to look when something is related to the CLI itself, and where to look when something is related to a specific template.
Try a template#
For a quick first look, generate a template in dry-run mode and show the resulting files before writing anything to disk:
boilerplates compose generate gitea --dry-run --show-files
That is still the main idea behind Boilerplates: instead of copying a static Docker Compose file and editing every domain, port, database, and secret manually, you generate a stack that already matches your choices.
New template runtime#
The biggest internal change in v0.2.0 is the new template runtime.
Templates are now built around a template.json manifest. This replaces the older template structure and makes templates more explicit, easier to validate, and easier to maintain over time.
Renderable template content now lives inside a dedicated files/ directory.
Conceptually, a template now looks like this:
template-name/
|-- template.json
`-- files/
|-- compose.yaml
`-- .env
The important part is the separation:
template.jsondescribes the templatefiles/contains the files that get rendered and generated
That may sound like a small structural change, but it makes a big difference for long-term template maintenance. Template authors get a clearer format, and users get templates that are easier to validate before generation.
Custom template delimiters#
Boilerplates no longer uses the default Jinja-style delimiters.
The new runtime uses:
<< >>for variables<% %>for blocks<# #>for comments
Example:
services:
app:
image: << app_image >>
environment:
TZ: << timezone >>
<% if traefik_enabled %>
labels:
- "traefik.enable=true"
- "traefik.http.routers.<< app_name >>.rule=Host(`<< app_domain >>`)"
<% endif %>
This is especially useful in infrastructure files.
Docker Compose files, Kubernetes manifests, Terraform files, Ansible files, and other config formats often already use curly braces somewhere. Moving Boilerplates to custom delimiters makes templates easier to read and reduces conflicts with other tools.
Better variables#
Variables are also more structured in v0.2.0.
The new model supports:
- more explicit variable configuration
- a dedicated
secretvariable type - placeholders
- sliders
- textarea-style input
- autogenerated secrets
This matters because templates are not just static files with a few replacements anymore. The variable model controls the generation experience.
For example, a database password should not behave like a normal text value. It should be treated as a secret, and in many cases it should be generated automatically if you do not provide one manually.
That makes templates cleaner for authors and safer for users.
Remote generation over SSH#
This is probably the most practical new feature for everyday use: Boilerplates can now generate templates directly on a remote server over SSH.
Instead of generating a stack locally, copying it to your server, checking paths, and then deploying it, you can generate directly to the target machine.
Check the available options:
boilerplates compose generate --help
The important new flags are:
--remote
--remote-path
Example flow:
boilerplates compose generate gitea \
--remote homelab-server \
--remote-path /opt/stacks/gitea
Use your own SSH host and target path here. The goal is simple: generate the template where it will actually run.
Dedicated Swarm module#
v0.2.0 also adds the first standalone swarm module with its own validation flow.
This is not meant to be oversold as a finished Swarm platform yet. It is the groundwork for a cleaner split between Compose workflows and Swarm workflows.
That matters because Compose and Swarm look similar in some places, but they are not the same deployment target. Having a dedicated module gives Boilerplates room to validate and generate Swarm-specific templates properly in the future.
What changed in v0.2.0#
The main changes are:
- the CLI app and template library are now separate repositories
- templates now use
template.json - renderable files now live in a dedicated
files/directory - templates use custom delimiters instead of default Jinja syntax
- variables have a more structured configuration model
- secret variables and autogenerated secrets are better supported
- templates can be generated directly on remote servers over SSH
- Swarm now has an initial dedicated module
Final thoughts#
Boilerplates v0.2.0 is mostly a foundation release.
Some of the changes are not flashy at first glance, especially the new manifest format and delimiter syntax. But they make the project much easier to maintain, and they make it easier to build better templates later.
For users, remote generation over SSH is the most immediately useful feature.
For template authors, template.json, the files/ directory, custom delimiters, and better variable modeling are the big improvements.
If you are using Boilerplates already, this is a good release to update to and test with your existing workflows.
