shantanoo-desai / komponist

A Composer for your favorite IoT/ IIoT container stacks with Ansible + Jinja2 + Docker Compose v2

komponist

A Composer for Docker Compose v2 Applications powered by Jinja2 + Ansible + Docker Compose v2. Komponist aims to reduce the effort of creating lengthy Docker Compose V2 powered stacks of popular open-source containers. Komponist brings the much needed logic of templating into Docker Compose applications.

Requirements

Komponist relies on the Shoulder of Giants to achieve a lot of configuration / templating abstraction. The following are required to make Komponist work:

OS Packages

Name	Version	Purpose
docker	>= 24.0.5	Container Runtime where your compose stacks will run
docker compose	>= 2.20.3	Docker Compose V2 Plugin for Docker Engine

Install them on your host accordingly. See Docker Documentations

Python Pip Packages

Name	Version	Purpose
ansible	>= 2.15.x	Almost all things within Komponist are achieved via ansible
passlib	1.7.x	required for password encryption hashing requirements for certain containers
docker	>5.x.x	required to control single container instances

Install these packages via:

pip install --user -r requirements.txt

Quickstart / Usage

Currently the following services are available to configure and run:

Service Name	Version
Node-RED	3.0.1
Mosquitto MQTT Broker	2.0.15
Traefik Reverse-Proxy	2.9.8
InfluxDB	1.8 2.6
TimescaleDB	v15
Telegraf	1.27.2
Grafana	9.5.1
QuestDB	7.1.1

These services can be further tuned using the files under the vars directory:

File	Purpose
config.yml	Core service configuration (API) endpoints and container image versions
creds.yml	Credentials for services (Username/Passwords/Databases)

Complete Komponist Stack

A complete stack with all the mentioned services above can be configured using:

ansible-playbook generate_stack.yml

This will generate all the respective configuration files and Docker Compose services files in the deploy directory in the root of the repository

Custom Komponist Stack

It is possible to generate the config.yml / creds.yml template files using a Terminal User-Interface (TUI).

1. create an examples/custom_stack directory:

   mkdir -p examples/custom_stack

2. use komponist-tui Docker Container to select and generate the configuration YAML files:

   docker run -it --rm \
       -v ./examples/custom_stack:/home/komponist \
       ghcr.io/shantanoo-desai/komponist-tui:main

3. select and fill out the prompts in the TUI which will generate a config.yml / creds.yml in examples/custom_stack directory

4. fill in the placeholder values in examples/custom_stack/creds.yml with your credentials

5. (OPTIONAL) encrypt the creds.yml using:

   ansible-vault encrypt examples/custom_stack/creds.yml

   enter a vault password and this will encrypt credentials

6. Bring the custom stack up:

   ansible-playbook -e "@examples/custom_stack/config.yml" \
       -e "@examples/custom_stack/creds.yml" \
       --ask-vault-pass \
       generate_stack.yml

   The --ask-vault-pass is required only if the credentials file is encrypted using Step 5

Bringing the Stack Up

You can bring the stack up using:

docker compose --project-directory=deploy up -d

Service Endpoints / Information

The following service names can be used to obtain log information using:

docker compose --project-directory=deploy logs -f <service_name>

Service Name	URL
nodered	http://localhost/nodered
mosquitto	mqtt://localhost:1883
traefik	N/A
telegraf	N/A
influxdvb1	http://localhost/influxdbv1
influxdbv2	http://influxdbv2.localhost
timescaledb	Not Configured to an API
grafana	http://localhost/grafana
questdb	http://questdb.localhost

Contributing / Development / Documentation

Contributions are welcome for additional services by opening feature requests as Issues. Please report bugs, erroneous behaviours as Issues.

If you would like to add your own Services / containers to Komponist, refer to the Development Workflow Guide.

All design decisions, inner workings are available in the docs directory.

Licensing

Komponist is licensed under Affero GNU Public License v3.0.