composia by fur.im

fur.im / composia

Fork 0

A self-hosted orchestration system crafted for power users. composia.xyz

Fork 0

composia site content docs guide service.de.md

11 kB

Markdown

at fix/direct-cli

alexma233 · refactor: clarify service folder semantics · 4mo ago

ec84c574

title: "Dienstkonfiguration" date: '2026-05-26T00:00:00+08:00' weight: 10 #

Jeder Dienst befindet sich in einem Verzeichnis der obersten Ebene innerhalb des Controller-Repositories. Ein Dienstverzeichnis enthält composia-meta.yaml und eine oder mehrere Docker-Compose-Dateien.

Minimaler Dienst:

name: my-app
nodes:
  - main

Mit dem Standardverhalten sucht Composia nach docker-compose.yaml im selben Verzeichnis.

Schlüssel der obersten Ebene #

Schlüssel	Typ	Erforderlich	Beschreibung
`name`	`string`	Ja	Eindeutiger Dienstname.
`project_name`	`string`	Nein	Docker-Compose-Projektname-Override. Standardmäßig ein normalisierter Dienstname.
`compose_files`	`[]string`	Nein	Compose-Dateipfade relativ zum Dienstverzeichnis.
`enabled`	`bool`	Nein	Ob der Dienst aktiv ist. Standardmäßig `true`.
`nodes`	`[]string`	Ja	Ziel-Node-IDs. Jede muss in `controller.nodes` existieren.
`infra`	`object`	Nein	Deklariert diesen Dienst als Caddy-, Rustic- oder Config-Only-Infrastruktur.
`network`	`object`	Nein	Caddy- und DNS-Einstellungen.
`update`	`object`	Nein	Image-Update-Einstellungen.
`data_protect`	`object`	Nein	Backup- und Restore-Datendefinitionen.
`backup`	`object`	Nein	Geplante Backups für geschützte Daten.
`migrate`	`object`	Nein	Migrationsfähige geschützte Daten.
`auto_deploy`	`bool`	Nein	Diesen Dienst nach Repository-Änderungen automatisch deployen.

compose_files-Einträge müssen relative Pfade sein, innerhalb des Dienstverzeichnisses bleiben und dürfen nicht dupliziert sein.

Infrastrukturdienste #

`infra.caddy` #

Deklariert den Caddy-Infrastrukturdienst des Repositories.

infra:
  caddy:
    compose_service: caddy
    config_dir: /etc/caddy

Schlüssel	Typ	Beschreibung
`compose_service`	`string`	Name des Compose-Dienstes. Standardmäßig `caddy`.
`config_dir`	`string`	Caddy-Konfigurationsverzeichnis. Standardmäßig `/etc/caddy`.

Nur ein Dienst kann als Caddy-Infrastruktur deklariert werden.

`infra.rustic` #

Deklariert den Rustic-Infrastrukturdienst des Repositories.

infra:
  rustic:
    compose_service: rustic
    profile: default
    data_protect_dir: /data-protect
    init_args:
      - --set-version
      - "2"

Schlüssel	Typ	Beschreibung
`compose_service`	`string`	Name des Compose-Dienstes. Standardmäßig `rustic`.
`profile`	`string`	Rustic-Profilname.
`data_protect_dir`	`string`	Container-Pfad, der auf `{StateDir}/data-protect` des Agenten gemappt wird.
`init_args`	`[]string`	Zusätzliche Argumente, die an `rustic init` übergeben werden. Leere Einträge werden abgelehnt.

Nur ein Dienst kann als Rustic-Infrastruktur deklariert werden.

`infra.config` #

Deklariert einen reinen Konfigurations-Infrastrukturdienst.

infra:
  config: {}

Config-Only-Dienste können nicht mit infra.caddy oder infra.rustic kombiniert werden. Ihre data_protect-Aktionen können nur files.copy verwenden.

Netzwerk #

`network.caddy` #

network:
  caddy:
    enabled: true
    source: Caddyfile

Schlüssel	Typ	Erforderlich	Beschreibung
`enabled`	`bool`	Nein	Aktiviert die Caddy-Verwaltung. Standardmäßig `false`.
`source`	`string`	Bed.	Caddyfile-Pfad relativ zum Dienstverzeichnis. Erforderlich, wenn aktiviert.

`network.dns` #

network:
  dns:
    provider: cloudflare
    hostname: app.example.com
    record_type: A
    value: 203.0.113.10
    proxied: true
    ttl: 120
    comment: Verwaltet von Composia

Schlüssel	Typ	Erforderlich	Beschreibung
`provider`	`string`	Ja	`cloudflare`, `alidns`, `dnspod`, `route53` oder `huaweicloud`.
`hostname`	`string`	Ja	DNS-Hostname.
`record_type`	`string`	Nein	Leer, `A`, `AAAA` oder `CNAME`.
`value`	`string`	Nein	DNS-Record-Wert. Multi-Node-Dienste sollten diesen explizit setzen.
`proxied`	`bool`	Nein	Provider-spezifischer Proxy-Umschalter, derzeit relevant für Cloudflare.
`ttl`	`uint32`	Nein	DNS-TTL.
`comment`	`string`	Nein	DNS-Record-Kommentar.

Image-Updates #

update:
  enabled: true
  auto_apply: false
  check_schedule: "0 */6 * * *"
  backup_before_update: true
  digest_pin: false
  backup_data:
    - name: db
      enabled: true
  discovery_sources:
    upstream:
      sources:
        - type: github
          repo: owner/repo
      combine: first_success
      include_prerelease: false
  images:
    app:
      image: ghcr.io/example/app
      current:
        env:
          file: .env
          key: APP_VERSION
      discovery: upstream
      filter:
        type: semver
        allow:
          - patch
          - minor

`update` #

Schlüssel	Typ	Beschreibung
`enabled`	`bool`	Aktiviert Update-Prüfungen für diesen Dienst.
`auto_apply`	`bool`	Wendet erkannte Updates automatisch an.
`check_schedule`	`string`	Cron-Zeitplan für Update-Prüfungen.
`backup_before_update`	`bool`	Führt Backups vor dem Anwenden von Updates aus.
`backup_data`	`[]object`	Geschützte Datenelemente, die vor dem Update gesichert werden sollen.
`digest_pin`	`bool`	Fixiert Images per Digest.
`discovery_sources`	`map[string]object`	Wiederverwendbare Erkennungsquellen. Benannte Quellen können nicht auf eine andere Quelle verweisen.
`images`	`map[string]object`	Update-Definitionen pro Image.

`update.backup_data[]` #

Schlüssel	Typ	Beschreibung
`name`	`string`	Name des geschützten Datenelements.
`enabled`	`bool`	Dieses Element ein- oder ausschließen.

`update.images.<name>` #

Schlüssel	Typ	Erforderlich	Beschreibung
`image`	`string`	Ja	Image-Repository.
`auto_apply`	`bool`	Nein	Per-Image-Override für automatisches Anwenden.
`check_schedule`	`string`	Nein	Per-Image-Prüfzeitplan.
`backup_before_update`	`bool`	Nein	Per-Image-Backup-Umschalter.
`digest_pin`	`bool`	Nein	Per-Image-Digest-Pin-Umschalter.
`current`	`object`	Ja	Aktuelle Versionsquelle.
`discovery`	`object` oder `string`	Ja	Erkennungskonfiguration oder benannte Erkennungsquellenreferenz.
`filter`	`object`	Bed.	Erforderlich, es sei denn, die Erkennung ist `digest`.

`current` #

Gib genau eines davon an:

Schlüssel	Beschreibung
`tag`	Statischer aktueller Tag.
`env.file` + `env.key`	Liest den aktuellen Tag aus einer Env-Datei. `file` muss relativ sein und innerhalb des Dienstverzeichnisses bleiben.
`yaml.file` + `yaml.path`	Liest den aktuellen Tag aus einer YAML-Datei. `file` muss relativ sein und innerhalb des Dienstverzeichnisses bleiben.

`discovery` #

Schlüssel	Typ	Beschreibung
`sources`	`[]object`	Mindestens eine Quelle.
`combine`	`string`	Leer, `merge` oder `first_success`.
`include_prerelease`	`bool`	Vorabversionen einschließen.

Erkennungsquellentypen:

Typ	Erforderliche Schlüssel	Hinweise
`auto`	Keine	`repo_url` ist optional und muss, wenn gesetzt, eine gültige URL sein. Muss die einzige Quelle sein.
`probe`	Keine	Erfordert `semver`-Filter, wenn ein Filter vorhanden ist.
`registry`	Keine	Registry-Tag-Erkennung.
`digest`	Keine	Muss die einzige Quelle sein. `filter` muss weggelassen werden.
`github`	`repo`	`repo` ist `owner/repo`.
`gitlab`	`project`	GitLab-Projekt-ID oder -Pfad.
`forgejo`	`repo`	`repo` ist `owner/repo`.

`filter` #

Typ	Erforderliche Schlüssel	Hinweise
`semver`	Keine	`allow` kann `patch`, `minor`, `major` enthalten.
`date`	`format`	Datumsformat zum Parsen von Tags.
`regex`	`pattern`, `order`	`order` muss `numeric` oder `lexicographic` sein.
`latest`	Keine	Verwendet den neuesten Kandidaten.

Datenschutz #

data_protect:
  data:
    - name: db
      backup:
        strategy: database.pgdumpall
        service: postgres
      restore:
        strategy: database.pgimport
        service: postgres
    - name: uploads
      backup:
        strategy: files.copy_after_stop
        include:
          - ./uploads
      restore:
        strategy: files.copy
        include:
          - ./uploads

`data_protect.data[]` #

Schlüssel	Typ	Erforderlich	Beschreibung
`name`	`string`	Ja	Eindeutiger Name des Datenelements.
`backup`	`object`	Nein	Backup-Aktion.
`restore`	`object`	Nein	Restore-Aktion.

Datenaktion #

Schlüssel	Typ	Erforderlich	Beschreibung
`strategy`	`string`	Ja	`files.copy`, `files.copy_after_stop`, `database.pgdumpall` oder `database.pgimport`.
`service`	`string`	Bed.	Erforderlich für `database.*`-Strategien. Name des Compose-Dienstes.
`include`	`[]string`	Bed.	Erforderlich für `files.*`-Strategien. `./...` oder Pfade mit `/` sind Dienstpfade; reine Namen sind Docker-Volume-Namen.

Backups #

backup:
  data:
    - name: db
      provider: rustic
      enabled: true
      schedule: "0 2 * * *"

Schlüssel	Typ	Erforderlich	Beschreibung
`name`	`string`	Ja	Muss auf einen `data_protect.data[].name` mit einer Backup-Aktion verweisen.
`provider`	`string`	Nein	Name des Backup-Providers.
`enabled`	`bool`	Nein	Aktiviert oder deaktiviert diesen Backup-Eintrag.
`schedule`	`string`	Nein	Cron-Zeitplan.

Migration #

migrate:
  data:
    - name: db
      enabled: true

Schlüssel	Typ	Erforderlich	Beschreibung
`name`	`string`	Ja	Muss auf einen `data_protect.data[].name` mit sowohl Backup- als auch Restore-Aktionen verweisen.
`enabled`	`bool`	Nein	Aktiviert oder deaktiviert die Migration für dieses Element.

title: "Dienstkonfiguration" date: '2026-05-26T00:00:00+08:00' weight: 10 #

Schlüssel der obersten Ebene #

Infrastrukturdienste #

infra.caddy #

infra.rustic #

infra.config #

Netzwerk #

network.caddy #

network.dns #