> ## 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

> Run file operations when a server starts, stops, or on demand

Workflows run a sequence of file operations on a serverhost. You can run them manually or whenever a server starts or stops.

This guide creates a backup workflow, runs it from the dashboard, and then shows you how to adapt it.

## Run the backup workflow

<Steps>
  <Step title="Create the workflow">
    Create `workflows/default/backup.yml` in your serverhost directory:

    ```yaml workflows/default/backup.yml theme={null}
    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 }}-{{ runtime.process-id }}"
          init-dir-if-missing: true
    ```
  </Step>

  <Step title="Load the workflow">
    Restart the serverhost. SimpleCloud uses the file path as the workflow ID, so this workflow becomes `default/backup`.
  </Step>

  <Step title="Assign the workflow">
    In the dashboard, open a server group or persistent server and go to **Settings > Workflows**. Under **Manual Workflows**, add `default/backup`.
  </Step>

  <Step title="Run the workflow">
    Start the server if it is not already running. Then open its actions menu and run `default/backup` to test the workflow.
  </Step>

  <Step title="Check the backup">
    On the serverhost, open:

    ```text theme={null}
    templates/.backup/<name>/<date>/<date-time>-<server>-<process-id>/
    ```

    Confirm that the final directory contains the files you expected. Its timestamp and process ID keep separate backup runs apart.
  </Step>
</Steps>

<Note>
  A workflow is available only on serverhosts that contain its file. If the affected servers can run on multiple serverhosts, add the same file to each one and restart them.
</Note>

The manual action copies files while the Minecraft server is running. Files that change during the copy, such as worlds and plugin data, may not form a consistent backup. For those files, add `default/backup` under **On Stop Workflows** and stop the server normally. Stop workflows run after the server process exits.

Place `default/backup` before `internal/cleanup`.

<Warning>
  `internal/cleanup` removes a group server's running directory. Any workflow that reads that directory must run before cleanup.
</Warning>

<Note>
  This workflow creates file copies but does not test restores or remove old backups. Verify that you can restore the data you need and manage retention for `templates/.backup/`.
</Note>

## Understand the workflow file

The backup workflow contains the same basic structure as every workflow:

* `name` identifies the workflow in serverhost logs.
* `steps` contains the operations in the order they run.
* `name` inside a step identifies that step in logs.
* `uses` selects the action. This workflow uses `simplecloud/copy`.
* `with` contains the values required by the action.

In this workflow, `from` points to the running server directory and `to` builds a unique backup path. If the source is missing, `init-dir-if-missing: true` creates an empty source directory instead of failing. Always verify that the resulting backup contains the expected files.

### Values used by the workflow

Values inside `{{ ... }}` are replaced when the workflow runs.

| Value                      | Result                                 |
| -------------------------- | -------------------------------------- |
| `{{ runtime.server-dir }}` | Running server directory               |
| `{{ runtime.templates }}`  | Serverhost template directory          |
| `{{ runtime.name }}`       | Server group or persistent server name |
| `{{ runtime.nice-id }}`    | Running server name, such as `lobby-1` |
| `{{ runtime.process-id }}` | Running process ID                     |
| `{{ time.now.date }}`      | Current date                           |
| `{{ time.now.dateTime }}`  | Current date and time                  |

## Adapt the backup workflow

Use the backup workflow as a starting point:

<Steps>
  <Step title="Copy the workflow">
    Copy `workflows/default/backup.yml` to a new path, such as `workflows/custom/world-backup.yml`.
  </Step>

  <Step title="Change the workflow">
    Give it a new `name`, then change the copy paths and exclusions for your task.
  </Step>

  <Step title="Reload the workflows">
    Restart every serverhost that contains the new file.
  </Step>

  <Step title="Assign the new ID">
    Add `custom/world-backup` under **Settings > Workflows**. A workflow ID is always its path below `workflows/`, without `.yml`.
  </Step>
</Steps>

### Change what gets copied

The `simplecloud/copy` action accepts these settings under `with`:

| Setting               | Purpose                                                                            |
| --------------------- | ---------------------------------------------------------------------------------- |
| `from`                | File or directory to copy                                                          |
| `to`                  | Destination for the copy                                                           |
| `replace`             | Whether to overwrite existing files; defaults to `true`                            |
| `exclude`             | Path or list of paths to leave out                                                 |
| `init-dir-if-missing` | Whether to create the source directory when it does not exist; defaults to `false` |

For example, add an `exclude` list to skip logs and caches while keeping the rest of the backup unchanged:

```yaml theme={null}
with:
  from: "{{ runtime.server-dir }}"
  to: "{{ runtime.templates }}/.backup/{{ runtime.name }}/{{ time.now.date }}/{{ time.now.dateTime }}-{{ runtime.nice-id }}-{{ runtime.process-id }}"
  init-dir-if-missing: true
  exclude:
    - "logs/**"
    - "cache/**"
```

Patterns in `exclude` are relative to `from`.

## Available actions

<AccordionGroup>
  <Accordion title="Copy files">
    `simplecloud/copy` copies a file or directory from `from` to `to`. Use `replace` to control whether existing files are overwritten and `exclude` to skip matching paths.
  </Accordion>

  <Accordion title="Create or extract archives">
    `simplecloud/compress` creates an archive and `simplecloud/decompress` extracts one. Both require `from` and `to`; `replace` is optional. The archive filename determines its format.
  </Accordion>

  <Accordion title="Upload a file">
    `simplecloud/upload` sends the file in `from` to the URL in `to`. It uploads files, not directories. You can also set the HTTP `method` and an `authorization-bearer` value.

    <Warning>
      Workflow files are plain text. Do not store long-lived access tokens in them.
    </Warning>
  </Accordion>

  <Accordion title="Delete files">
    `simplecloud/delete` removes the configured `path`. Use `min-age`, such as `7d`, to keep newer files.

    <Warning>
      Delete paths are not limited to the server directory. Check the final path before running the workflow.
    </Warning>
  </Accordion>

  <Accordion title="Repeat steps">
    `simplecloud/foreach` runs nested steps for each entry in `items`. Set `as` to the variable name used by the nested `steps`.
  </Accordion>
</AccordionGroup>

## Built-in workflows

| Workflow           | Purpose                                      |
| ------------------ | -------------------------------------------- |
| `internal/setup`   | Prepares the server directory before startup |
| `internal/cleanup` | Cleans up files after the server stops       |

<Warning>
  Keep `internal/setup` and `internal/cleanup` assigned unless you intentionally replace their behavior.
</Warning>

## Troubleshooting

<AccordionGroup>
  <Accordion title="The workflow is not listed">
    Workflow IDs are entered manually in the dashboard. Confirm the file exists on the serverhost, restart the serverhost, and add the ID again.
  </Accordion>

  <Accordion title="The workflow cannot be found">
    Check that the ID matches the file path. For example, `custom/world-backup` must point to `workflows/custom/world-backup.yml`.
  </Accordion>

  <Accordion title="A backup is missing">
    Check the serverhost logs for `Backup Workflow` and `copy-running-to-backup`. For an automatic backup, also confirm that `default/backup` comes before `internal/cleanup`.
  </Accordion>
</AccordionGroup>