> ## Documentation Index
> Fetch the complete documentation index at: https://simplecloud.app/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Workflows

> Definiere Server-Vorbereitung und Cleanup mit Serverhost-Workflows

## Was Workflows sind

Workflows sind YAML-Dateien, die der Serverhost während der Vorbereitung oder beim Cleanup eines Servers ausführt. Sie kopieren Template-Dateien, laden konfigurierte Plugins herunter, wenden Configurators an, verwalten Cache-Dateien und entfernen temporäre Laufzeitverzeichnisse.

Workflow-Dateien liegen in `workflows/`. Die Workflow-ID besteht aus Namespace und Dateiname ohne `.yml`, zum Beispiel `internal/setup` für `workflows/internal/setup.yml`.

## Standard-Workflows

Jeder Serverhost erstellt beim ersten Start die Standard-Workflow-Dateien:

| Workflow           | Zweck                                                                                |
| ------------------ | ------------------------------------------------------------------------------------ |
| `internal/setup`   | Bereitet ein Serververzeichnis vor, bevor der Prozess startet                        |
| `internal/cleanup` | Kopiert Cache- und Log-Daten und entfernt temporäre Verzeichnisse dynamischer Server |

Servergruppen und persistente Server speichern ihre Workflows in der Basiskonfiguration:

```yaml theme={null}
workflows:
  when:
    start:
      - internal/setup
    stop:
      - internal/cleanup
```

Das Dashboard verwaltet die üblichen Standardwerte für dich. Bearbeite Workflow-Dateien direkt nur, wenn du eigene Vorbereitung, Backups, Uploads oder Cleanup-Schritte brauchst.

## Workflow-Struktur

Ein Workflow hat einen lesbaren `name`, optionale `variables` und eine `steps`-Liste. Jeder Step hat einen `name`, einen `uses`-Action-Identifier, optionale `if`- und `async`-Einstellungen und Action-Parameter unter `with`.

```yaml theme={null}
# workflows/default/backup.yml
name: Backup Workflow

steps:
  - name: copy-running-to-backup
    uses: simplecloud/copy
    with:
      from: "{{ runtime.server-dir }}"
      to: "{{ runtime.templates }}/.backup/{{ runtime.name }}/{{ time.now.date }}/{{ time.now.dateTime }}-{{ runtime.nice-id }}"
      init-dir-if-missing: true
```

Variablen sind hilfreich, wenn mehrere Steps denselben Pfad oder Wert verwenden:

```yaml theme={null}
name: Archive World

variables:
  backup-dir: "{{ runtime.templates }}/.backup/{{ runtime.name }}/{{ time.now.date }}"

steps:
  - name: compress-world
    uses: simplecloud/compress
    with:
      from: "{{ runtime.server-dir }}/world"
      to: "{{ vars.backup-dir }}/world.zip"
```

## Runtime-Werte

Workflow-Ausdrücke verwenden `{{ ... }}`-Syntax. Die wichtigsten Werte sind:

| Wert                              | Beschreibung                                            |
| --------------------------------- | ------------------------------------------------------- |
| `{{ runtime.name }}`              | Gruppenname oder Name des persistenten Servers          |
| `{{ runtime.nice-id }}`           | Laufzeitname, zum Beispiel `lobby-1`                    |
| `{{ runtime.type }}`              | Gemappter Servertyp, zum Beispiel `server` oder `proxy` |
| `{{ runtime.persistent }}`        | Ob es ein persistenter Server ist                       |
| `{{ runtime.numerical-id }}`      | Numerische ID bei Gruppenservern                        |
| `{{ runtime.server-dir }}`        | Verzeichnis des Servers, der vorbereitet wird           |
| `{{ runtime.templates }}`         | Template-Wurzelverzeichnis                              |
| `{{ runtime.port }}`              | Zugewiesener Server-Port                                |
| `{{ runtime.software }}`          | Server-Software aus dem Blueprint                       |
| `{{ runtime.mapped-software }}`   | Plattformgemappter Software-Name                        |
| `{{ runtime.minecraft-version }}` | Minecraft-Version aus dem Blueprint                     |
| `{{ runtime.configurator }}`      | Configurator aus dem Blueprint                          |
| `{{ runtime.tags }}`              | Tags der Gruppe oder des persistenten Servers           |
| `{{ runtime.properties.<key> }}`  | Eigene Property aus der Basiskonfiguration              |
| `{{ vars.<key> }}`                | Variable aus dem Workflow oder einem `foreach`-Step     |
| `{{ time.now.date }}`             | Aktuelles lokales Datum, hilfreich für Backup-Ordner    |

## Häufige Actions

### `simplecloud/copy`

Kopiert eine Datei oder ein Verzeichnis.

```yaml theme={null}
- name: copy-template
  uses: simplecloud/copy
  with:
    from: "{{ runtime.templates }}/{{ runtime.name }}"
    to: "{{ runtime.server-dir }}"
    init-dir-if-missing: true
    replace: false
```

| Feld                  | Beschreibung                                                                 |
| --------------------- | ---------------------------------------------------------------------------- |
| `from`                | Quelldatei oder Quellverzeichnis                                             |
| `to`                  | Zieldatei oder Zielverzeichnis                                               |
| `replace`             | Ob vorhandene Dateien überschrieben werden. Standard ist `true`              |
| `init-dir-if-missing` | Erstellt ein fehlendes Quellverzeichnis und fährt fort. Standard ist `false` |
| `exclude`             | Optionaler Pfad oder Liste von Pfaden/Globs, die übersprungen werden         |

### `simplecloud/delete`

Löscht eine Datei oder ein Verzeichnis.

```yaml theme={null}
- name: delete-running-dir
  uses: simplecloud/delete
  if: "{{ runtime.persistent }} == false"
  with:
    path: "{{ runtime.server-dir }}"
```

Optionale Felder sind `force` und `min-age`, zum Beispiel `10m`, `2h` oder `7d`.

### `simplecloud/foreach`

Führt verschachtelte Steps für jedes Element einer Liste aus.

```yaml theme={null}
- name: copy-tagged
  uses: simplecloud/foreach
  with:
    items: "{{ runtime.tags }}"
    as: tag
    steps:
      - name: copy-tag-{{ vars.tag }}
        uses: simplecloud/copy
        with:
          from: "{{ runtime.templates }}/_tagged/{{ vars.tag }}"
          to: "{{ runtime.server-dir }}"
          replace: false
```

### `simplecloud/load-plugins`

Lädt konfigurierte Plugins von Modrinth, Hangar, Spigot oder direkten URLs herunter und kopiert sie in das Plugin-Verzeichnis des Servers.

```yaml theme={null}
- name: load-plugins
  uses: simplecloud/load-plugins
  with:
    minecraft-version: "{{ runtime.minecraft-version }}"
    platform: "{{ runtime.software }}"
    plugins-dir: "{{ runtime.server-dir }}/plugins"
    cache-dir: "{{ runtime.cache-dir }}"
    type: "{{ runtime.type }}"
```

### `simplecloud/configurate`

Wendet einen Configurator aus `options/configurators/` an.

```yaml theme={null}
- name: configurate-server
  uses: simplecloud/configurate
  with:
    configurator: "{{ runtime.configurator }}"
    dir: "{{ runtime.server-dir }}"
```

Siehe [Configurators](/docs/de/manual/configuration/configurators) für das Configurator-Dateiformat.

### Archive und Uploads

Nutze `simplecloud/compress`, `simplecloud/decompress` und `simplecloud/upload` für Backups oder externe Speicher-Workflows.

```yaml theme={null}
- name: compress-world
  uses: simplecloud/compress
  with:
    from: "{{ runtime.server-dir }}/world"
    to: "{{ runtime.templates }}/.backup/{{ runtime.name }}/world.zip"
```

```yaml theme={null}
- name: upload-backup
  uses: simplecloud/upload
  with:
    from: "{{ runtime.templates }}/.backup/{{ runtime.name }}/world.zip"
    to: "https://example.com/backups/world.zip"
    method: PUT
```

## Bedingungen und Async-Steps

Nutze `if`, um einen Step nur auszuführen, wenn eine Bedingung passt. Bedingungen unterstützen Vergleiche, `&&`, `||`, `exists(...)`, `!exists(...)` und `value(path, default)`.

```yaml theme={null}
- name: copy-logs-to-archive
  uses: simplecloud/copy
  if: "{{ runtime.persistent }} == false"
  with:
    from: "{{ runtime.server-dir }}/logs/"
    to: "{{ runtime.templates }}/cache/logs/{{ runtime.name }}/{{ runtime.nice-id }}"
```

Setze `async: true` nur für unabhängige Steps. Der Workflow wartet auf asynchrone Arbeit, bevor er Erfolg oder Fehler meldet.

## Fehlerbehebung

<AccordionGroup>
  <Accordion title="Ein Workflow läuft nicht">
    Prüfe die Workflow-Liste der Servergruppe oder des persistenten Servers. Die Workflow-ID muss zum Pfad unter `workflows/` passen, zum Beispiel `internal/setup`.
  </Accordion>

  <Accordion title="Ein Workflow kann nicht geladen werden">
    Stelle sicher, dass die YAML-Datei `name` und `steps` enthält und dass jeder Step einen `uses`-Action-Identifier hat.
  </Accordion>

  <Accordion title="Ein Wert wird nicht ersetzt">
    Verwende Syntax wie `{{ runtime.name }}` oder `{{ vars.name }}`. Prozent-Platzhalter wie `%server-dir%` gehören zu Configurators, nicht zu Workflows.
  </Accordion>

  <Accordion title="Plugin- oder Template-Dateien fehlen">
    Prüfe den Quellpfad der betroffenen `simplecloud/copy`-Action und ob `init-dir-if-missing` für diesen Ordner aktiviert werden sollte.
  </Accordion>
</AccordionGroup>