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

# systemd Service

> Set up and operate the VARIOS AI update helper (varios.sh) as a systemd service

For on-premise installations, VARIOS AI provides the `varios.sh` script. It runs in the background, watches the `update_version` file, and automatically performs an update when a new target version is set (pull Docker images, restart containers, run migration scripts).

To ensure the update helper starts reliably after a server reboot, you can register it as a **systemd service**.

<Note>
  Docker must be installed and startable. `After=docker.service` defines startup order; `Wants=docker.service` starts Docker when this service starts — even if Docker is not enabled for boot. We also recommend `systemctl enable docker.service` for server reboots. The service runs `varios.sh --daemon` directly — output goes to **journald**, not `varios.log`.
</Note>

***

## Service file

Set `WorkingDirectory` to the directory containing `varios.sh`:

```ini varios-update.service theme={null}
[Unit]
Description=Start varios.sh
After=docker.service
Wants=docker.service

[Service]
Type=simple
ExecStart=/bin/sh ./varios.sh --daemon
WorkingDirectory=/docker/varios/

[Install]
WantedBy=multi-user.target
```

***

## Setup

<Steps>
  <Step title="Adjust WorkingDirectory">
    Set `WorkingDirectory` in `varios-update.service` to the absolute path of the VARIOS installation directory containing `varios.sh`, `docker-compose.yml`, and `.env` (e.g. `/docker/varios/`).
  </Step>

  <Step title="Install the service file and reload systemd">
    ```bash theme={null}
    cp varios-update.service /etc/systemd/system/
    systemctl daemon-reload
    ```

    <Warning>
      Without `daemon-reload`, systemd will not pick up the new service file — `enable` or `start` will fail.
    </Warning>
  </Step>

  <Step title="Enable and start the service">
    ```bash theme={null}
    systemctl enable --now varios-update.service
    ```
  </Step>

  <Step title="Verify the setup">
    ```bash theme={null}
    systemctl status varios-update.service
    ```

    The status should show `active (running)`.

    <Check>
      Follow logs live: `journalctl -u varios-update.service -f`
    </Check>
  </Step>
</Steps>

***

## Operations

Control the helper **only via systemd** — not via `./varios.sh --stop`. The systemd service runs `varios.sh --daemon` directly in the foreground and does **not** create `varios.pid`. `./varios.sh --stop` only works if the helper was previously started manually without systemd.

```bash theme={null}
# Check status
systemctl status varios-update.service

# Stop update monitoring (e.g. before maintenance)
systemctl stop varios-update.service

# Start update monitoring again
systemctl start varios-update.service

# Disable autostart (service keeps running until stopped)
systemctl disable varios-update.service
```

<Warning>
  `systemctl stop` stops update **monitoring**. Any in-flight `docker compose` commands during an update may be interrupted, because systemd terminates the service process and its child processes (`KillMode=control-group`).
</Warning>

***

## Logs and troubleshooting

| Source                   | Command                                                | Content                            |
| ------------------------ | ------------------------------------------------------ | ---------------------------------- |
| systemd (primary)        | `journalctl -u varios-update.service -f`               | Update checks, update flow, errors |
| systemd (recent entries) | `journalctl -u varios-update.service -n 50 --no-pager` | Recent history for troubleshooting |

`varios.log` and `varios.pid` are only created when you start `./varios.sh` **without** systemd — not when operating via this service.

### Common checks

<AccordionGroup>
  <Accordion title="Service does not start">
    * Is Docker running? `systemctl status docker.service`
    * Does `WorkingDirectory` point to the installation directory?
    * Was `systemctl daemon-reload` run after copying the service file?
    * Details: `journalctl -u varios-update.service -n 50 --no-pager`
  </Accordion>

  <Accordion title="Service is running but no update occurs">
    * Does `.env` contain the current `VERSION=`?
    * Does `update_version` contain a different target version?
    * Check the log: `journalctl -u varios-update.service -f`
  </Accordion>

  <Accordion title="Helper is running twice">
    * Check for an additionally started manual helper: `pgrep -af varios.sh`
    * Stop manually started helper: `./varios.sh --stop` (only if `varios.pid` exists)
    * Stop systemd-managed helper: `systemctl stop varios-update.service`
  </Accordion>
</AccordionGroup>