[![Build Docker Image](https://github.com/DerDavidBohl/dirigent-spring/actions/workflows/build.yml/badge.svg)](https://github.com/DerDavidBohl/dirigent-spring/actions/workflows/build.yml) # Dirigent Tool to manage your docker compose deployments via git. ## Table of Contents - [Screenshots](#screenshots) - [Why Dirigent?](#why-dirigent) - [Setup](#setup) - [docker-compose](#docker-compose) - [docker CLI](#docker-cli) - [Environment Variables](#environment-variables) - [deployments.yml](#deploymentsyml) - [Volumes](#volumes) - [Step by Step (Gitea)](#step-by-step-gitea) - [API](#api) - [Gitea Webhook](#gitea-webhook) - [Deployments](#deployments) - [Start](#start) - [All Deployments](#all-deployments) - [Deployment by name](#deployment-by-name) - [Stop](#stop) - [Deployment by name](#deployment-by-name-1) - [State](#state) - [Develop](#develop) - [Setup for local Tests](#setup-for-local-tests) - [Roadmap](#roadmap) ## Screenshots ![image](https://github.com/user-attachments/assets/2e0ab3e1-d702-4cc2-9c05-055dc41136ff) ## 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 ```yml 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 - DIRIGENT_UPDATES_DISABLED= # optional 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 ```bash 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= \ #optional -e DIRIGENT_UPDATES_DISABLED= \ -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) | | | DIRIGENT_UPDATES_DISABLED | Disable Update Feature |`false` | ### 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`: ```yaml 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: ```yaml 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:///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. ```yaml 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:///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:///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 ```json { "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