# Was ist HELIOS?

> Was HELIOS auf dem Server tut: die Installation per Skript, die drei Bereiche im Browser und die Dateien compose.yaml und .env, die es dabei schreibt.

**HELIOS** ist eine Web-App, die neben SOLECTRUS auf demselben Server läuft. Sie installiert SOLECTRUS und hält die Konfiguration danach aktuell.

## HELIOS installieren

Die Installation startet dieser Befehl im Terminal des Servers:

```bash
curl -fsSL https://raw.githubusercontent.com/solectrus/helios/main/bootstrap/install.sh | bash
```

Das Skript geht diese Schritte durch:

1. **Docker** – Fehlt es, bietet das Skript an, es über [get.docker.com](https://get.docker.com) nachzuinstallieren.
2. **Verzeichnis** – Zur Wahl stehen `/opt/solectrus` (als `root`), `~/solectrus` und das aktuelle Verzeichnis. Dort landen `compose.yaml`, `.env` und die Daten aller Dienste, auch die Datenbanken. Für eine andere Platte: das Verzeichnis vorher anlegen, hineinwechseln und das Skript dort starten.
3. **Bestehende Installation** – Läuft SOLECTRUS auf dem Server schon, erkennt das Skript die Dienste und bietet an, HELIOS dort einzutragen, statt eine neue Installation anzulegen.
4. **Start** – Das Skript erzeugt ein Admin-Passwort, startet die Dienste und nennt am Ende die Adresse: `http://<server>:3999`, dazu das Passwort. Es steht auch in der `.env`.

Die Konfiguration folgt danach im Browser. Der Quelltext des Skripts lässt sich vorher lesen: [install.sh](https://github.com/solectrus/helios/blob/main/bootstrap/install.sh).

## Was HELIOS verwaltet

SOLECTRUS besteht aus mehreren Docker-Containern, die per `docker compose` zusammenlaufen. Beschrieben werden sie in zwei Dateien: `compose.yaml` listet die Dienste, `.env` enthält die [Umgebungsvariablen](/docs/referenz/).

Beide Dateien gehören HELIOS. Es erzeugt sie nach jeder Änderung an der Konfiguration komplett neu. Ansehen lassen sie sich im Browser, unter _Konfiguration_ am unteren Rand.

Die Dienste selbst wissen nichts von HELIOS. Sie lesen nur ihre Umgebungsvariablen. HELIOS entscheidet lediglich, welche Variablen dabei mit welchen Werten in der `.env` landen.

## Die drei Bereiche

### Konfiguration

- **Sensoren** – Welche Messwerte SOLECTRUS führt und woher sie kommen. Rund 50 Sensoren stehen zur Auswahl, von der PV-Erzeugung bis zur Wallbox. Zu jedem Sensor zeigt HELIOS den aktuellen Messwert aus der InfluxDB, so lässt sich die Zuordnung sofort prüfen.
- **Datenquellen** – Woher die Messwerte kommen: [SENEC](/docs/referenz/senec-collector/), [Shelly](/docs/referenz/shelly-collector/), [MQTT](/docs/referenz/mqtt-collector/) oder eine [Prognose](/docs/referenz/forecast-collector/) für die PV-Erzeugung. Bei den Geräten prüft HELIOS auf Knopfdruck, ob sie erreichbar sind und die Zugangsdaten stimmen.
- **Grundeinstellungen** – Zeitzone, Inbetriebnahme der Anlage, Zugriffsschutz, Farbschema, CO₂-Faktor, eigene Domain samt HTTPS, Speicherorte, Software-Stand, Betriebsmodus und die dynamischen Strompreise samt preisoptimierter Speicherbeladung.

### Dienste

Die Übersicht aller Container mit Status, Version und Aktualität. Von hier aus lassen sich einzelne Dienste starten und stoppen oder gleich alle auf einmal. **Aktualisieren** gibt es nur je Dienst: HELIOS lädt dann das Image neu und erzeugt den Container neu. Die Protokolle jedes Dienstes lassen sich direkt im Browser lesen.

> **Änderungen greifen erst nach einem Neustart**
>
>
> Nach einer Änderung an der Konfiguration schreibt HELIOS die neuen Dateien sofort, lässt die laufenden Dienste aber unberührt. Die Statusleiste meldet dann _Konfiguration geändert – Neustart erforderlich_ und nennt die betroffenen Dienste. Ein Klick auf **Alle Dienste neu starten** übernimmt die Änderung. Einzeln geht es auch: **Aktualisieren** in der Zeile des Dienstes.
>

### Datensicherung

Sicherungen von Konfiguration und Messwerten, siehe [Erstellen von Datensicherungen](/docs/anleitungen/datensicherung/).

## Bestehende Installation übernehmen

Läuft SOLECTRUS auf dem Server bereits, ist kein Neuanfang nötig. Das Installationsskript erkennt die laufenden Dienste und trägt HELIOS in deren `compose.yaml` ein, statt eine neue anzulegen.

Beim ersten Aufruf im Browser liest HELIOS `compose.yaml` und `.env` ein und übernimmt die bestehende Konfiguration, samt der Sensor-Zuordnungen. Vorher legt es beide Dateien als `.bak` zur Seite.

## Der Container

HELIOS gehört zu den Diensten, die es verwaltet: Es steht mit einem eigenen Service in der `compose.yaml`, die es selbst schreibt, und bekommt seine Updates über [Watchtower](/docs/referenz/watchtower/) wie jeder andere Dienst.

### Zugriff auf Docker

Die anderen Dienste steuert HELIOS über den Docker-Socket des Hosts, der als Volume in den Container gereicht wird:

```yaml
volumes:
  - /var/run/docker.sock:/var/run/docker.sock
```

Damit kann HELIOS Container starten, stoppen, neu erzeugen und ihre Protokolle lesen. Ein entfernter Docker-Host ist deshalb nicht möglich, siehe [Was HELIOS nicht kann](#was-helios-nicht-kann).

Dazu kommt das cgroup-Verzeichnis des Hosts, nur lesend:

```yaml
volumes:
  - /sys/fs/cgroup:/host/sys/fs/cgroup:ro
```

Darüber liest HELIOS den tatsächlichen Speicher- und CPU-Verbrauch des Hosts. Ohne dieses Volume sieht ein HELIOS-Container in einem Proxmox-LXC nicht die Werte des Containers, sondern die des physischen Knotens.

### Eigene Daten

Das Verzeichnis, in dem `compose.yaml` und `.env` liegen, ist im Container als `/data` eingehängt. Dort schreibt HELIOS beide Dateien, und dort legt es auch seine eigenen Daten ab:

```
/data/compose.yaml
/data/.env
/data/helios/config.yaml
/data/helios/primary.sqlite3
```

In `config.yaml` steht die Konfiguration, so wie sie im Browser eingegeben wurde. Sie ist die Quelle: `compose.yaml` und `.env` erzeugt HELIOS daraus, sobald sich die `config.yaml` geändert hat. Gesichert wird bei einer [Datensicherung](/docs/anleitungen/datensicherung/) ebenfalls die `config.yaml`.

Die SQLite-Datenbank hält den übrigen Zustand von HELIOS, etwa den Verlauf der Datensicherungen.

### Erreichbarkeit

Ohne eigene Domain veröffentlicht HELIOS den Port **3999** auf dem Host. Die Oberfläche läuft dann über HTTP, erreichbar unter `http://<server>:3999`.

Mit einer eigenen Domain samt HTTPS, eingerichtet unter _Konfiguration → Grundeinstellungen → Eigene Domain_, veröffentlicht der HELIOS-Container selbst keinen Port mehr. Stattdessen nimmt Traefik den Verkehr an und reicht ihn weiter. Die Oberfläche liegt dann auf derselben Domain wie das Dashboard, weiterhin unter Port 3999, aber per HTTPS und mit einem Zertifikat von Let's Encrypt: `https://<domain>:3999`.

## Updates

Zu den Diensten gehört [Watchtower](/docs/referenz/watchtower/). Es prüft regelmäßig auf neue Versionen und installiert sie automatisch, HELIOS selbst eingeschlossen. Näheres unter [Installation von Updates](/docs/anleitungen/updates/).

## Was HELIOS nicht kann

HELIOS verwaltet einen Docker-Host über dessen lokalen Docker-Socket. Daraus ergeben sich ein paar Grenzen:

- **Kein Docker Swarm, kein Kubernetes.** HELIOS arbeitet mit `docker compose`, nicht mit anderen Orchestrierern.
- **Kein zweites Verwaltungswerkzeug.** `compose.yaml` und `.env` schreibt HELIOS selbst. Liegen die SOLECTRUS-Dienste als Stack in Portainer oder einem ähnlichen Werkzeug, gehören die Dateien diesem Werkzeug. Beides nebeneinander geht nicht.
- **Keine externen Datenbanken.** PostgreSQL, Redis und InfluxDB laufen auf demselben Host. Einzige Ausnahme ist eine entfernte InfluxDB im Betriebsmodus _Nur Kollektoren_.
- **Kein entfernter Docker-Host.** HELIOS braucht den lokalen `docker.sock`.
- **Keine beliebigen Images.** HELIOS erzeugt die `compose.yaml` vollständig neu. Beim Übernehmen einer bestehenden Installation muss es daher jeden Dienst kennen. Stößt es auf ein fremdes Image, verweigert es den Import und nennt den Dienst beim Namen. Ein paar bekannte Zusatzdienste wie `dozzle` lässt es stehen und reicht sie unverändert durch.

Ein gemischter Betrieb ist trotzdem möglich: Was HELIOS nicht abdeckt, läuft daneben weiter. HELIOS braucht lediglich die alleinige Hoheit über `compose.yaml` und `.env` der SOLECTRUS-Dienste.

## Support-Paket

HELIOS erzeugt unter _Support_ auf Knopfdruck ein **Support-Paket** mit Konfiguration, Protokollen und einer Momentaufnahme des Systems. Wozu es dient, steht unter [Support](/docs/support/).

## Quelltext

HELIOS ist in Ruby on Rails implementiert, der Quelltext ist auf GitHub verfügbar: \
[github.com/solectrus/helios](https://github.com/solectrus/helios)