Introduction

Kompozit is a tool inspired by Kustomize. While Kustomize simplifies Kubernetes configurations, Kompozit does the same for docker-compose. It enables you to customize and patch docker-compose.yaml files efficiently, reducing redundancy and improving maintainability.

Why Kompozit? 🤔

Managing multiple docker-compose configurations can be cumbersome. For instance:

• You have a docker-compose-traefik.yaml for a Traefik reverse proxy.

• You need different setups for:

1. A simple home server (docker-compose-traefik-simple.yaml).

2. A public website with additional security (docker-compose-traefik-secured.yaml).

These configurations share most content, but a few details differ. This leads to duplication and makes updates tedious. 😵‍💫

Enter Kompozit! 🎉

Kompozit lets you:

1. 📂 Store your base configurations in a reusable “base” folder.

2. ✏️ Define overlays for different setups (e.g., “home server” or “public website”).

3. 🔄 Apply patches to the base configuration without modifying it directly.

Example Use Case 💡

Base Configuration 🏗️

Start with a base folder containing your generic docker-compose setup.

$ tree base/
base/
├── docker-compose-traefik.yml
└── kompozition.yml

• docker-compose-traefik.yml: The base Traefik configuration. 🛳️

• kompozition.yml: Declares resources for Kompozit to process. 📜

kompozition.yml:

resources:
  - docker-compose-traefik.yml

docker-compose-traefik.yml:

networks:
  public:
    attachable: true
    internal: false
  private:
    attachable: true
    internal: true

volumes:
  acme:

services:
  traefik:
    image: traefik:latest
    hostname: traefik
    container_name: traefik
    restart: unless-stopped
    environment:
      DUCKDNS_TOKEN: "${DUCKDNS_TOKEN}"
      CLOUDFLARE_DNS_API_TOKEN: "${CLOUDFLARE_DNS_API_TOKEN}"
    ports:
      - 80:80/tcp
      - 443:443/tcp
    networks:
      - public
      - private
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock
      - acme:/letsencrypt

This setup is the reusable core of your configuration. 🔧

Overlay Customization 🖍️

Now, create overlays for specific use cases. 🗂️

$ tree overlay/
overlay/
├── homeserver
│   ├── docker-compose-traefik-patch.yml
│   └── kompozition.yaml
└── public_wordpress
    ├── docker-compose-traefik-patch.yml
    └── kompozition.yaml

Each overlay:

1. References the base configuration. 🗺️

2. Applies patches specific to the use case. 🛠️

overlay/homeserver/kompozition.yaml:

resources:
  - ../../base

patchesStrategicMerge:
  - path: docker-compose-traefik-patch.yml

overlay/homeserver/docker-compose-traefik-patch.yml:

services:
  traefik:
    command:
      - "--log.level=INFO"
      - "--api.insecure=false"
      - "--api.dashboard=true"
      - "--providers.docker=true"
      - "--providers.docker.exposedByDefault=false"
      - "--global.sendAnonymousUsage=false"
      - "--global.checkNewVersion=false"
    labels:
      - com.centurylinklabs.watchtower.enable=true

Run Kompozit 🏃‍♂️

Use Kompozit to generate the final patched configuration. 🧩

$ kompozit -b overlay/homeserver/
networks:
  public:
    attachable: true
    internal: false
  private:
    attachable: true
    internal: true

volumes:
  acme: null

services:
  traefik:
    image: traefik:latest
    hostname: traefik
    container_name: traefik
    restart: unless-stopped
    labels:
      - com.centurylinklabs.watchtower.enable=true
    environment:
      DUCKDNS_TOKEN: ${DUCKDNS_TOKEN}
      CLOUDFLARE_DNS_API_TOKEN: ${CLOUDFLARE_DNS_API_TOKEN}
    ports:
      - 80:80/tcp
      - 443:443/tcp
    networks:
      - public
      - private
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock
      - acme:/letsencrypt
    command:
      - --log.level=INFO
      - --api.insecure=false
      - --api.dashboard=true
      - --providers.docker=true
      - --providers.docker.exposedByDefault=false
      - --global.sendAnonymousUsage=false
      - --global.checkNewVersion=false

Deploy the Final Configuration 🚢

Redirect the output to a file and deploy it using Docker Compose. 🎯

$ kompozit -b overlay/homeserver/ > final-docker-compose.yml
$ docker-compose -f final-docker-compose.yml up -d