mirror of
https://github.com/DerDavidBohl/dirigent-spring.git
synced 2026-02-14 18:18:42 -06:00
224 lines
9.2 KiB
Markdown
224 lines
9.2 KiB
Markdown
[](https://github.com/DerDavidBohl/dirigent-spring/actions/workflows/build.yml)
|
||
|
||
# <img src="https://raw.githubusercontent.com/DerDavidBohl/dirigent-spring/latest/assets/icon-background.svg" width="80px"></img> 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)
|
||
|
||
## 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.
|
||
|
||
Ideal for Self-hosters managing multiple services (e.g., Nextcloud, Gitea, Vaultwarden).
|
||
|
||
## Setup
|
||
|
||
### docker-compose
|
||
|
||
```yml
|
||
services:
|
||
app:
|
||
image: ghcr.io/derdavidbohl/dirigent-spring:latest
|
||
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
|
||
|
||
```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= \
|
||
|
||
-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:latest
|
||
```
|
||
|
||
### 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`:
|
||
|
||
```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://<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.
|
||
```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://<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`
|
||
|
||
## 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 ;)
|