Write a Template from Scratch#
A valid template that can be used by fengine only consists of a few components:
A Git repository in which the template resides.
A
fengine.yaml
file that contains the templates metadata.A
template/
subdirectory that contains the files that should be rendered into the incarnation.
Create a New Template#
To initialize a new, empty template you need to create the elements described in the list above. If you’re lazy, just use the following set of bash commands to do that:
# create template scaffolding
fengine new mytemplate
# initialize git repository
git init
git commit -am 'initial commit'
Be aware that only the files within the template/
directory will be rendered into the incarnation.
Therefore you can use the root directory of the template Git repository to place other subdirectories or files for documentation,
tests or a CI configuration file for the template repository itself.
Template Configuration#
In the above section you’ve just created an empty template configuration in the fengine.yaml
file.
There are a few things you can configure for a template:
Template Variables#
Probably the most important template configuration are variables or template data.
Every template can have zero or more variables that it must define in the fengine.yaml
file
and which can be used in files inside the template/
folder. When an incarnation is being rendered
these variables are being substituted in the defined places.
Tip
foxops uses Jinja to render the template files, including the variables.
Variables can be defined with the following syntax:
variables:
<variable_1_name>:
type: string | integer | boolean
description: <some description for this variable>
default: <an optional default value>
The values in <>
are meant to be replaced, for example to define a variable called name
of type string
with the default Jane Doe
use the following:
variables:
name:
type: string
description: The name of the author
default: Jane Doe
More variable types exist (like complex objects or lists): Read more about this in the template configuration reference.
Exclude Files from Rendering#
Sometimes you don’t want to render every file in template/
, but only copy&paste them as-is
to the incarnation. You can use the exclude_files
field to list the files you don’t want
to have render with Jinja.
For example to exclude the files template/dummy
and all *.txt
files in template/
from rendering
use the following config:
exclude_files:
- 'dummy'
- '*.txt'
variables:
...
Change an Existing Template#
Nothing special to consider here. Just change the files in the repository and commit to git as normal.
As best practice we recommend to version your template on the main branch using git tags like v1.2.0
(for example following semantic versioning or calendar versioning). Especially in production environments it’s strongly recommended to always specify exact version numbers (= git tags) when reconciling incarnations with foxops.
Tip
Learn here how to make template changes in a backwards-compatible way.