You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: README.md
+55-42Lines changed: 55 additions & 42 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -1,51 +1,58 @@
1
1
# Docker Compose Templer
2
2
3
-
This little Python 3 program adds more dynamics to [Docker Compose or Docker Stack files](https://docs.docker.com/compose/compose-file/) by utilizing the [Jinja2 template engine](http://jinja.pocoo.org/).
3
+
This is a little Python3 utility that adds more dynamism to [Docker Compose or Docker Stack files](https://docs.docker.com/compose/compose-file/) by utilizing the [Jinja2 template engine](http://jinja.pocoo.org/).
4
4
5
-
Docker Compose (DC) files allow [variable substitution](https://docs.docker.com/compose/compose-file/#variable-substitution)with environment variables. This functionality offers very simple dynamics that can be used for customizing specific options of the DC file during startup. When a single DC file shall be used to create different service instances with varying environment variables, networks, volumes, etc., the simple method of variable substitution is not convenient. Therefore I decided to create this Python program to introduce templating with Jinja2 to DC files. A definition file says where to find the templates, what variables to use for rendering and where to put the resulting files.
5
+
Docker Compose (DC) files are quite static in nature. It is possible to use [variable substitution](https://docs.docker.com/compose/compose-file/#variable-substitution)to run slightly different container configurations based on a single DC file. This, however, doesn't allow complex variations in networks, volumes, etc. and proper code reuse. Therefore I decided to create this Python program to introduce Jinja2 templating to DC files. A _definition file_ says where to find the templates, what variables to use and where to put the rendered files.
6
6
7
-
The documentation of Jinja2 can be found [here](http://jinja.pocoo.org/docs/dev/templates/).
7
+
The documentation on the Jinja2 syntax can be found [here](http://jinja.pocoo.org/docs/dev/templates/).
8
8
9
9
**Features:**
10
10
11
11
* templating using Jinja2
12
-
* using some [extra Jinja filters](#extra-jinja2-filters) (comply with Ansible filters)
13
-
* monitoring of file changes and automatic rendering of templates (especially useful during development)
14
12
* using YAML syntax for definition and variable files
13
+
* monitoring of file changes and automatic rendering of templates (especially useful during development)
14
+
* using some [extra Jinja filters](#extra-jinja2-filters) (comply with Ansible filters)
Render Docker Compose file templates with the power of Jinja2
@@ -66,24 +73,32 @@ optional arguments:
66
73
The definition file defines what to do. It lists template and the variables to be used for rendering and says where to put the resulting file. The definition file syntax is as follows:
67
74
68
75
```yaml
69
-
# define global variables to be used in all templates - can contain Jinja syntax
76
+
#(optional) define global variables to be used in all templates - can contain Jinja syntax
70
77
vars:
71
78
some_global_var: foo
72
79
another_global_var: "{{some_global_var}}bar"# will render to 'foobar'
73
80
74
-
# load global variables from YAML file(s) (order matters) - can contain Jinja syntax
81
+
#(optional) load global variables from YAML file(s) (order matters) - can contain Jinja syntax
75
82
include_vars:
76
83
- path/to/file_1.yml
77
84
- path/to/file_2.yml
78
85
86
+
# (optional) Command to execute before any template of this definition file is rendered
- src: templates/my_template.yml.j2 # source file as Jinja2 template (Jinja syntax can be used on path)
83
96
dest: stacks/s1/my_instance.yml # path for resulting file (Jinja syntax can be used on path)
84
-
include_vars: variables/s1.yml # include local variables from YAML file(s)
85
-
vars: # local variables for this template
97
+
include_vars: variables/s1.yml # (optional) include local variables from YAML file(s)
98
+
vars: # (optional) local variables for this template
86
99
some_local_var: abc
100
+
pre_render: "echo 'Now creating {dest} from {src}...'"# (optional) Command to execute before rendering this template
101
+
post_render: "echo 'Successfully created {dest} from {src}'"# (optional) Command to execute after rendering this template
87
102
88
103
# second template
89
104
- src: templates/my_template.yml.j2
@@ -118,26 +133,24 @@ Because of the omit functionality the renderer only renders YAML files, generic
118
133
119
134
### Examples
120
135
121
-
Examples can be found in the [`examples`](examples) directory. There are three stacks defined, one global stack and two user stacks. The user stacks define a _Nextloud_ and _Redis_ service. Both stacks depend on the global one, meaning those share a global _MariaDB_ and a reverse proxy.
136
+
Examples can be found in the [`examples`](examples) directory. There are three stacks defined, one global stack and two user stacks. The user stacks define a _Nextloud_ and _Redis_ service. Both stacks depend on the global one, meaning those share a global _MariaDB_ and a reverse proxy. To run this example execute the following command inside the `examples/` directory: `docker_compose_templer -f stack-global.yml stack-user1.yml stack-user2.yml`
122
137
123
138
## Extra Jinja2 Filters
124
139
125
-
In addition to the [Jinja built-in filters](http://jinja.pocoo.org/docs/2.10/templates/#builtin-filters) the following extra filters are implemented. The filter are based on the filter in Ansible:
126
-
127
-
Filter* | Description
128
-
--------|------------
129
-
`mandatory(msg)`| If the variable is not defined an error with a message `msg` will be thrown.
130
-
`regex_escape`| Escape special characters to safely use a string in a regex search.
131
-
`regex_findall(pattern[, ignorecase, multiline])` | Find all occurrences of regex matches.<br>Default values: `ignorecase=False`, `multiline=False`
132
-
`regex_replace(pattern, replacement[, ignorecase, multiline])` | Perform a regex search and replace operation.<br>Default values: `ignorecase=False`, `multiline=False`
133
-
`regex_search(pattern[, groups, ignorecase, multiline])` | Search with regex. If one or more match `groups` are specified the search result will be a list containing only those group matches. The groups are specified either by their position (e.g. `\1`) or by their name (e.g. foo: `\gfoo`).<br>Default values: `ignorecase=False`, `multiline=False`
134
-
`regex_contains(pattern[, ignorecase, multiline])` | Yields `true` if the string contains the given regex pattern.<br>Default values: `ignorecase=False`, `multiline=False`
135
-
`to_bool([default_value])`| Converts a string to a bool value. The `default_value` will be used if the string cannot be converted.
136
-
`to_yaml([indent, ...])` | Converts a value to YAML.<br>Default values: `indent=2`
137
-
`to_json([...])`| Converts a value to JSON.
138
-
`to_nice_json([indent])` | Converts a value to human readable JSON.<br>Default values: `indent=4`
139
-
140
-
> \* Arguments enclosed with brackets are optional
140
+
In addition to the [Jinja built-in filters](http://jinja.pocoo.org/docs/latest/templates/#builtin-filters) the following extra filters are implemented. The filter are based on the filter in Ansible:
`mandatory(msg)`| If the variable is undefined an error with a message `msg` will be thrown.
145
+
`regex_escape()`| Escape special characters to safely use a string in a regex search.
146
+
`regex_findall(pattern, ignorecase=False, multiline=False)`| Find all occurrences of regex matches.
147
+
`regex_replace(pattern, replacement, ignorecase=False, multiline=False)`| Perform a regex search and replace operation.
148
+
`regex_search(pattern, groups, ignorecase=False, multiline=False)` | Search with regex. If one or more match `groups` are specified the search result will be a list containing only those group matches. The groups are specified either by their position (e.g. `\1`) or by their name (e.g. foo: `\gfoo`).
149
+
`regex_contains(pattern, ignorecase=False, multiline=False)`| Yields `true` if the string contains the given regex pattern.
150
+
`to_bool(default_value=None)`| Converts a string to a bool value. The `default_value` will be used if the string cannot be converted.
151
+
`to_yaml(indent=2, [...])`| Converts a value to YAML.
152
+
`to_json([...])`| Converts a value to JSON.
153
+
`to_nice_json(indent=2, [...])`| Converts a value to human readable JSON.
0 commit comments