Skip to content

Commit cb54a1f

Browse files
aisberggaisbergg
committed
Add documentation
1 parent 4a3949d commit cb54a1f

File tree

1 file changed

+149
-0
lines changed

1 file changed

+149
-0
lines changed

‎README.md‎

Lines changed: 149 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,149 @@
1+
# Docker Compose Templer
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/).
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.
6+
7+
The documentation of Jinja2 can be found [here](http://jinja.pocoo.org/docs/dev/templates/).
8+
9+
**Features:**
10+
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+
* using YAML syntax for definition and variable files
15+
16+
**Table of contents:**
17+
<!-- TOC depthFrom:2 depthTo:6 withLinks:1 updateOnSave:0 orderedList:0 -->
18+
19+
- [Installation](#installation)
20+
- [Usage](#usage)
21+
- [Command line arguments](#command-line-arguments)
22+
- [Definition File](#definition-file)
23+
- [Templates](#templates)
24+
- [Examples](#examples)
25+
- [Extra Jinja2 Filters](#extra-jinja2-filters)
26+
- [License](#license)
27+
28+
<!-- /TOC -->
29+
30+
---
31+
32+
## Installation
33+
34+
Install directly from Github:
35+
```
36+
pip install git+https://github.com/Aisbergg/python-docker-compose-templer@v1.0.1
37+
```
38+
39+
Install from PyPi:
40+
```
41+
pip install docker-compose-templer
42+
```
43+
44+
## Usage
45+
### Command line arguments
46+
47+
```
48+
usage: docker_compose_templer [-a] [-f] [-h] [-v] [--version]
49+
definition_file [definition_file ...]
50+
51+
Render Docker Compose file templates with the power of Jinja2
52+
53+
positional arguments:
54+
definition_file File that defines what to do.
55+
56+
optional arguments:
57+
-a, --auto-render Monitor file changes and render templates automatically
58+
-f, --force Overwrite existing files
59+
-h, --help Show this help message and exit
60+
-v, --verbose Enable verbose mode
61+
--version Print the program version and quit
62+
```
63+
64+
### Definition File
65+
66+
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+
68+
```yaml
69+
# define global variables to be used in all templates - can contain Jinja syntax
70+
vars:
71+
some_global_var: foo
72+
another_global_var: "{{some_global_var}}bar" # will render to 'foobar'
73+
74+
# load global variables from YAML file(s) (order matters) - can contain Jinja syntax
75+
include_vars:
76+
- path/to/file_1.yml
77+
- path/to/file_2.yml
78+
79+
# template definitions
80+
templates:
81+
# first template
82+
- src: templates/my_template.yml.j2 # source file as Jinja2 template (Jinja syntax can be used on path)
83+
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
86+
some_local_var: abc
87+
88+
# second template
89+
- src: templates/my_template.yml.j2
90+
dest: stacks/s2/my_instance.yml
91+
vars:
92+
some_local_var: xyz
93+
```
94+
95+
The variables can itself contain Jinja syntax, you only have to make sure the variables are defined prior usage. The different sources of variables are merged together in the following order:
96+
97+
1. global `include_vars`
98+
2. global `vars`
99+
3. template `include_vars`
100+
4. template `vars`
101+
102+
### Templates
103+
104+
The templates are rendered with Jinja2 using the global and local variables defined in the definition file. Any Jinja2 specific syntax can be used.
105+
106+
In addition to the [extra filters](#extra-jinja2-filters) the variable `omit` can be used in the templates. This concept is borrowed from Ansible and the purpose is to omit options from the DC file where a variable is not defined. In the following example the env variable `VAR2` will be omitted from the template if `my_var` was not defined in the definition file:
107+
108+
```yaml
109+
services:
110+
foo:
111+
environment:
112+
- "VAR1=abc"
113+
- "VAR2={{ my_var|default(omit) }}"
114+
...
115+
```
116+
117+
Because of the omit functionality the renderer only renders YAML files, generic file types do not work.
118+
119+
### Examples
120+
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.
122+
123+
## Extra Jinja2 Filters
124+
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
141+
142+
## Todo
143+
144+
* Add `pre_render` and `post_render` options
145+
* Write more tests
146+
147+
## License
148+
149+
_Docker Compose Templer_ is released under the LGPL v3 License. See [LICENSE.txt](LICENSE.txt) for more information.

0 commit comments

Comments
 (0)