Dirigent

Tool to manage your docker compose deployments via git.

Table of Contents

• Screenshots
• Why Dirigent?
• Setup
  • docker-compose
  • docker CLI
  • Environment Variables
  • deployments.yml
  • Volumes
  • Step by Step (Gitea)
• API
  • Gitea Webhook
  • Deployments
    • Start
      • All Deployments
      • Deployment by name
    • Stop
      • Deployment by name
    • State
• Develop
  • Setup for local Tests
• Roadmap

Screenshots

Why Dirigent?

TL;DR: Dirigent brings GitOps simplicity to Docker Compose.

Dirigent simplifies GitOps for Docker Compose deployments by automating the management of your containers through Git. Here’s why you should use it:

✅ Git-Centric Deployments

• Version-controlled infrastructure: Track changes to your Docker Compose setups via Git, ensuring reproducibility and auditability.
• Automated sync: Push changes to your Git repo, and Dirigent handles deployment — no manual docker compose commands needed.

🔄 Seamless Git Integration

• Webhook-driven updates: Trigger deployments automatically when your repo changes
• Centralized management: Define all deployments in a single deployments.yml file for easy orchestration.

🚀 Self-Hosting Made Simple

• Designed for homelabs & private clouds: Perfect for developers who self-host with Docker and want Git-based control.
• No Kubernetes complexity: Lightweight alternative to full-blown GitOps tools like ArgoCD or Flux—just Docker Compose + Git.

🔧 Extensible & Developer-Friendly

• REST API: Integrate with existing tools (CI/CD, monitoring).
• Gotify notifications: Get alerts when deployments fail.

🔒 Encrypted Secrets

• You can store encrypted Secrets that are injected as Environment Variable on execution

Ideal for Self-hosters managing multiple services (e.g., Nextcloud, Gitea, Vaultwarden).

Setup

docker-compose

services:
  app:
    image: ghcr.io/derdavidbohl/dirigent-spring:1
    container_name: dirigent-app
    restart: unless-stopped
    environment:
      - DIRIGENT_DEPLOYMENTS_GIT_URL= # required
      - DIRIGENT_SECRETS_ENCRYPTION_KEY= # Has to be 16 Chars. Can be generated with `openssl rand -base64 12`
      - DIRIGENT_COMPOSE_COMMAND= # optional
      - DIRIGENT_GIT_AUTHTOKEN= # optional
      - DIRIGENT_START_ALL_ON_STARTUP= # optional
      - DIRIGENT_DEPLOYMENTS_SCHEDULE_ENABLED= # optional
      - DIRIGENT_DEPLOYMENTS_SCHEDULE_CRON= # optional
      - DIRIGENT_GOTIFY_BASEURL= # optional
      - DIRIGENT_GOTIFY_TOKEN= # optional
      - DIRIGENT_INSTANCENAME= # optional but recommended
    ports:
      - 8080:8080
    volumes:
      - /path/to/config:/app/config
      - /path/to/deployments:/app/deployments
      - /path/to/data:/app/data
      - /var/run/docker.sock:/var/run/docker.sock

docker CLI

docker run -d \
  --name=dirigent \
  -e DIRIGENT_DEPLOYMENTS_GIT_URL= \
  -e DIRIGENT_SECRETS_ENCRYPTION_KEY= \ # Has to be 16 Chars. Can be generated with `openssl rand -base64 12`
  #optional
  -e DIRIGENT_COMPOSE_COMMAND= \
  #optional
  -e DIRIGENT_GIT_AUTHTOKEN= \
  #optional
  -e DIRIGENT_STARTALL_ON_STARTUP= \
  #optional
  -e DIRIGENT_DEPLOYMENTS_SCHEDULE_ENABLED= \
  #optional
  -e DIRIGENT_DEPLOYMENTS_SCHEDULE_CRON= \
  #optional
  -e DIRIGENT_GOTIFY_BASEURL= \
  #optional
  -e DIRIGENT_GOTIFY_TOKEN= \
  #optional but recommended
  -e DIRIGENT_INSTANCENAME= \

  -v /path/to/config:/app/config \
  -v /path/to/deployments:/app/deployments \
  -v /path/to/data:/app/data \
  -v /var/run/docker.sock:/var/run/docker.sock \
  ghcr.io/derdavidbohl/dirigent-spring:1

Environment Variables

Variable	Description	Default
DIRIGENT_DEPLOYMENTS_GIT_URL	URL to your deployments git repository
DIRIGENT_SECRETS_ENCRYPTION_KEY	Encryption Key to save encrypted secrets. Has to be 16 Chars. Can be generated with openssl rand -base64 12
DIRIGENT_COMPOSE_COMMAND	Command to run your docker-compose files	docker compose
DIRIGENT_GIT_AUTHTOKEN	Auth token with access to your repos
DIRIGENT_START_ALL_ON_STARTUP	Start all deployments on startup	true
DIRIGENT_DEPLOYMENTS_SCHEDULE_ENABLED	enable scheduled start of all deployments	true
DIRIGENT_DEPLOYMENTS_SCHEDULE_CRON	cron expression for scheduled start of all deployments (second minute hour day(month) month day(week)	* */5 * * * *
DIRIGENT_GOTIFY_BASEURL	Gotify Base URL for Notification, when deployments fail
DIRIGENT_GOTIFY_TOKEN	Gotify Token for Notification, when deployments fail
DIRIGENT_INSTANCENAME	Name of your Instance (will be shown in Web UI)

deployments.yml

The deployments.yml contains the list of repos you want to deploy. Every deployment needs a name and a source. You can optionally define an order, if one deployment depends on another deployment.

Here is an example of a deployments.yml:

deployments:
  - name: test1
    source: https://github.com/url/tomyrepo1.git
  - name: test2
    source: https://github.com//url/tomyrepo2.git
    order: 10

Volumes

Volume	Description
/app/config	Config directory for Dirigent
/app/deployments	Deployments directory for Dirigent
/app/data	Data directory containing the database
/var/run/docker.sock	Docker socket for Dirigent

Step by Step (Gitea)

Setup Deployments Repo

1. Create a new repository in Gitea
2. Create a new file deployments.yml in the root of your repository with the following content:

   deployments: []
   

3. Deploy the dirigent app as described above. Set the DIRIGENT_DEPLOYMENTS_GIT_URL to the URL of your repository. Dont forget to set the DIRIGENT_GIT_AUTHTOKEN if your repository is private.
4. Optional: Create a new webhook in your repository. Set the URL to http://<dirigent-host-and-port>/api/v1/gitea

Add Deployments

1. Create a git repository for your deployment
2. Add a docker-compose.yml to your repository
3. Add a new entry to the deployments.yml in your deployments repository with the name of your deployment and the URL to your deployment repository. Optionally you can set an order, if your deployment depends on another deployment.

   deployments:
     - name: test1
       source: https://url/toyourdeploymentrepo.git
       order: 10 # optional
   

4. Optional: Add a new webhook in your deployment repository. Set the URL to http://<dirigent-host-and-port>/api/v1/gitea

Optional good practice:

Store all your repositories for one host in one gitea organization. This way you only have to set up one webhook at organization level.

API

Gitea Webhook

POST to http://<dirigent-host-and-port>/api/v1/gitea

Deployments

Start

Parameters

Parameter	Description
forceRecreate=true	forces recreation of the targeted deployment(s)

All Deployments:

POST to /api/v1/deployments/all/start

Deployment by name:

POST to /api/v1/deployments/{name}/start

Stop

Deployment by name:

POST to /api/v1/deployments/{name}/stop

State

GET to /api/v1/deployment-states

Secrets

Model

{
  "key": "string",
  "value": "string",
  "environmentVariable": "string",
  "deployments": ["string"]
}

Get Secrets

GET to /api/v1/secrets

Save Secret

PUT to /api/v1/secrets/{key}

Delete Secret

DELETE to /api/v1/secrets/{iey}

Develop

Setup for local Tests

1. copy src/test/resources/application-local.properties.template to src/test/resources/application-local.properties
2. fill in your test repository url and auth token
3. Done ;)

Roadmap

Here is a roadmap with future Ideas

• Automate Updates for deployments - Work in Progress
• Add automated tests
• Add cleanups (i. e. docker system prune or docker volume prune)
• Add a single repo mode
• Improve pathhandling for deployment related files in repo
• Multiple Dirigent hosts