Konfiguration

Diese Seite behandelt die installationsbezogene Konfiguration: Controller-Konfiguration, Agent-Konfiguration, Web-Umgebungsvariablen und Age-Schlüssel-Einrichtung.

Dienstdefinitionen befinden sich in composia-meta.yaml. Siehe Dienst-Leitfaden für diese Datei.

Aufbau der Konfigurationsdatei

Controller und Agent verwenden dasselbe YAML-Dateiformat. Eine Datei kann einen oder beide Abschnitte enthalten:

controller:
  # Controller-Einstellungen

agent:
  # Agent-Einstellungen

Mindestens einer von controller oder agent muss vorhanden sein.

Wenn dieselbe Konfigurationsdatei beide Abschnitte enthält, wird der lokale Agent als eingebauter Node behandelt:

• agent.node_id muss main sein.
• controller.nodes muss einen Eintrag mit id: main enthalten.
• controller.repo_dir und agent.repo_dir dürfen nicht derselbe Pfad sein.

Setze controller.remote_config.enabled nur dann auf true, wenn die authentifizierte CLI und Web-UI die eingeschränkte Controller-Konfigurationsansicht bearbeiten dürfen. Das Controller-Konfigurationsverzeichnis muss für den Controller-Prozess beschreibbar sein; die standardmäßige Docker-Compose-Bereitstellung bindet es für diese optionale Funktion beschreibbar ein.

Der Editor stellt ein künstliches YAML-Dokument bereit, nicht die vollständige Konfiguration. Ausgelassene bearbeitbare Felder behalten ihre aktuellen Werte. Unbekannte Felder, YAML-Aliase, Merge-Schlüssel, das Hinzufügen oder Entfernen von Nodes sowie alle Secret- und Zugangsdatenfelder werden abgelehnt. Aktualisierungen verwenden eine Dateirevision und atomaren Austausch. Eine erfolgreiche Antwort bedeutet, dass die neue Konfiguration validiert und das Neuladen des Controller-Laufzeitprozesses eingeplant wurde. Falls der neue Laufzeitprozess nicht bereit wird, stellt der Controller die vorherige Konfiguration wieder her.

Vollständige Konfigurationsvorlage

Diese Vorlage zeigt jeden unterstützten installationsbezogenen Schlüssel. Sie ist eine Formreferenz, kein kopierbarer Standard. Entferne Abschnitte, die du nicht verwendest, entferne leere Listeneinträge und verwende entweder Inline-Werte oder _file-Werte für jedes secret-artige Feld.

controller:
  listen_addr: ":7001"
  repo_dir: "/data/repo-controller"
  state_dir: "/data/state-controller"
  log_dir: "/data/logs"

  # Der CLI- und Web-UI-Editor ist standardmäßig deaktiviert.
  remote_config:
    enabled: false

  access_tokens:
    - name: "web"
      token: "REPLACE_WITH_WEB_ACCESS_TOKEN"
      token_file: ""
      enabled: true
      comment: "Web-UI-Zugriffstoken"

  nodes:
    - id: "main"
      display_name: "Main"
      enabled: true
      public_ipv4: ""
      public_ipv6: ""
      token: "REPLACE_WITH_MAIN_AGENT_TOKEN"
      token_file: ""

  git:
    remote_url: ""
    branch: "main"
    pull_interval: ""
    author_name: "Composia"
    author_email: "composia@example.com"
    auth:
      username: ""
      token: ""
      token_file: ""

  backup:
    default_schedule: ""

  updates:
    default_check_schedule: ""
    auto_apply: false
    backup_before_update: true
    digest_pin: false
    semver:
      default_allow:
        - patch
        - minor
    forge_auth:
      github:
        url: "https://github.com"
        token: ""
        token_file: ""
        api_url: "https://api.github.com"
      gitlab:
        url: "https://gitlab.com"
        token: ""
        token_file: ""
        api_url: "https://gitlab.com/api/v4"
      forgejo:
        url: "https://forgejo.example.com"
        token: ""
        token_file: ""
        api_url: ""

  auto_deploy:
    infra: false
    services: false

  dns:
    cloudflare:
      api_token: ""
      api_token_file: ""
      zones: []
    alidns:
      access_key_id: ""
      access_key_id_file: ""
      access_key_secret: ""
      access_key_secret_file: ""
      security_token: ""
      security_token_file: ""
      region_id: ""
      zones: []
    dnspod:
      secret_id: ""
      secret_id_file: ""
      secret_key: ""
      secret_key_file: ""
      session_token: ""
      session_token_file: ""
      region: ""
      zones: []
    route53:
      access_key_id: ""
      access_key_id_file: ""
      secret_access_key: ""
      secret_access_key_file: ""
      session_token: ""
      session_token_file: ""
      region: ""
      profile: ""
      hosted_zone_id: ""
      zones: []
    huaweicloud:
      access_key_id: ""
      access_key_id_file: ""
      secret_access_key: ""
      secret_access_key_file: ""
      region_id: ""
      zones: []

  rustic:
    main_nodes:
      - "main"
    maintenance:
      forget_schedule: ""
      prune_schedule: ""

  secrets:
    provider: age
    identity_file: "/app/configs/age-identity.key"
    recipient_file: ""
    armor: true

  notifications:
    alertmanager:
      enabled: true
      listen_path: "/api/v1/alerts"
    smtp:
      enabled: false
      host: ""
      port: 587
      encryption: starttls
      username: ""
      password: ""
      password_file: ""
      from: ""
      to: []
      on: []
      task_sources: []
    telegram:
      enabled: false
      bot_token: ""
      bot_token_file: ""
      chat_id: ""
      on: []
      task_sources: []

agent:
  controller_addr: "http://controller:7001"
  controller_grpc: false
  controller_headers:
    - name: ""
      value: ""
      value_file: ""
  node_id: "main"
  token: "REPLACE_WITH_MAIN_AGENT_TOKEN"
  token_file: ""
  repo_dir: "/data/repo-agent"
  state_dir: "/data/state-agent"
  caddy:
    generated_dir: ""

Behalte keine leeren Listeneinträge wie controller_headers mit einem leeren name. Sie werden nur zur Dokumentation der unterstützten Objektform gezeigt.

Das Web-Zugriffstoken und das Haupt-Agent-Token müssen unterschiedlich sein.

Age-Schlüssel-Einrichtung

controller.secrets ist optional. Konfiguriere es nur, wenn du Composia-verwaltete verschlüsselte Secrets verwendest.

Wenn controller.secrets konfiguriert ist, ist identity_file erforderlich. recipient_file ist optional. Wenn es weggelassen wird, leitet Composia den Empfänger vom privaten Schlüssel ab.

Generiere einen privaten Schlüssel:

age-keygen -o age-identity.key

Optionale Empfängerdatei:

age-keygen -y age-identity.key > age-recipients.txt

Verwende den privaten Schlüssel in der Konfiguration:

secrets:
  provider: age
  identity_file: "/app/configs/age-identity.key"

Oder verwende beide Dateien:

secrets:
  provider: age
  identity_file: "/app/configs/age-identity.key"
  recipient_file: "/app/configs/age-recipients.txt"

armor ist optional und standardmäßig true.

Controller-Konfigurationsreferenz

Erforderliche Schlüssel

Optionale Schlüssel der obersten Ebene

nodes[]

*Verwende entweder token oder token_file, nicht beides.

access_tokens[]

Zugriffstokens dürfen Node-Tokens oder andere Zugriffstokens nicht duplizieren.

git

secrets

Dieser gesamte Abschnitt ist optional. Wenn der Abschnitt vorhanden ist, gelten diese Regeln:

backup

updates

Jeder Forge-Auth-Eintrag unterstützt:

auto_deploy

dns

rustic

notifications.alertmanager

notifications.smtp

notifications.telegram

Agent-Konfigurationsreferenz

*Verwende entweder token oder token_file, nicht beides.

controller_headers[]

caddy

Web-Umgebungsvariablen

Der Webserver liest Umgebungsvariablen. In Docker Compose werden diese über .env gesetzt.

Inline-Werte und _file-Werte

Viele secret-artige Felder unterstützen sowohl Inline-Werte als auch Dateireferenzen. Beispiele:

• token / token_file
• password / password_file
• api_token / api_token_file
• value / value_file

Verwende nur eine Form. Wenn beide gesetzt sind, schlägt der Start fehl.