80 lines
4.1 KiB
Markdown
80 lines
4.1 KiB
Markdown
# Getting Started
|
||
|
||
Dieser Leitfaden beschreibt ausschließlich den Docker-Deploy über die bereitgestellten GHCR-Images und die anschließende Einrichtung im UI.
|
||
|
||
## Voraussetzungen
|
||
- Docker & Docker Compose
|
||
- Portainer-Instanz (Business Edition empfohlen; bei Community/Edge zusätzlich Agent einsetzen)
|
||
|
||
## Zentrale Umgebungsvariablen (Kurzfassung)
|
||
| Variable | Erforderlich | Beschreibung |
|
||
|----------|--------------|--------------|
|
||
| `PORTAINER_URL` | Nein | Basis-URL zu Portainer; kann im Setup-UI hinterlegt werden, falls nicht gesetzt. |
|
||
| `PORTAINER_API_KEY` | Nein | API-Key; kann im Setup gespeichert werden (wird verschlüsselt). |
|
||
| `PORTAINER_SERVER_NAME` | Nein | Anzeige-Name für den initialen Servereintrag. |
|
||
| `PORTAINER_API_SECRET` | Nein | AES-Schlüssel für gespeicherte API-Keys; setze stabilen Wert, sonst muss der Key neu eingegeben werden. |
|
||
| `SUPERUSER_USERNAME`, `SUPERUSER_EMAIL`, `SUPERUSER_PASSWORD` | Nein | Legt automatisch einen Superuser an, falls noch keiner existiert; sonst im Setup-UI anlegen. |
|
||
| `SELF_STACK_ID` | Nein | ID des StackPulse-Stacks; schützt vor Self-Redeploy. |
|
||
| `AUTH_COOKIE_NAME`, `AUTH_SESSION_TTL_MS`, `AUTH_COOKIE_SECURE` | Nein | Session/Cookie-Tuning (Name, Dauer, Secure-Flag). |
|
||
| `SECURITY_PHRASE_SECRET` | Nein | Secret für verschlüsselte Sicherheitsphrasen; stabil halten, sonst Phrasen neu verteilen. |
|
||
| `PORTAINER_SSH_SECRET` | Nein | Secret für verschlüsselte SSH-Passwörter; stabil halten, sonst Passwort neu setzen. |
|
||
| `DISPLAY` | Nein | Wird an Update-Childprozesse weitergereicht (Default `:9999`). |
|
||
|
||
Weitere Variablen (Agent, Registry, mTLS) findest du im Detail unter [Umgebungsvariablen](environment.md). Einstellungen wie Server-URL/API-Key, SSH-Config oder Update-Skript kannst du alternativ im UI (Setup/Wartung) verwalten.
|
||
|
||
**Hinweis zu Secrets:**
|
||
- `SECURITY_PHRASE_SECRET` und `PORTAINER_SSH_SECRET` steuern die AES-256-GCM-Verschlüsselung von Sicherheitsphrasen bzw. hinterlegten SSH-Passwörtern.
|
||
- Wenn sie nicht gesetzt sind, nutzt StackPulse fixe Fallbacks (`stackpulse-security-phrase-secret` bzw. `stackpulse-portainer-ssh-secret` / API-Key). Setze in Produktion eigene, stabile Werte – ein späterer Secret-Wechsel macht zuvor gespeicherte Phrasen/Passwörter unlesbar.
|
||
- Eine vollständige Übersicht aller Variablen (inkl. Agent) findest du unter „Technik → Umgebungsvariablen“.
|
||
|
||
## Ersteinrichtung im UI
|
||
1. Öffne das Frontend.
|
||
2. Lege den Portainer-Server und den zugehörigen API-Key an (der Wizard führt durch den Test).
|
||
3. Registriere einen Superuser oder verwende den per Umgebungsvariablen automatisch angelegten Account.
|
||
4. Nach erfolgreicher Einrichtung kannst du dich anmelden und erhältst Zugriff auf Dashboard, Logs, Benutzer & Wartung.
|
||
|
||
## Docker Run (Single Container)
|
||
```bash
|
||
docker run -d \
|
||
-p 4001:4001 \
|
||
-e PORTAINER_URL=https://portainer.example.com \
|
||
-e PORTAINER_API_KEY=xxxx \
|
||
-e SUPERUSER_USERNAME=admin \
|
||
-e SUPERUSER_EMAIL=admin@example.com \
|
||
-e SUPERUSER_PASSWORD=changeme \
|
||
-e SELF_STACK_ID=123 \
|
||
-e SECURITY_PHRASE_SECRET=$(openssl rand -hex 32) \
|
||
-e PORTAINER_SSH_SECRET=$(openssl rand -hex 32) \
|
||
-v stackpulse_data:/app/backend/data \
|
||
ghcr.io/mboehmlaender/stackpulse:latest
|
||
```
|
||
Das Volume `stackpulse_data` persistiert die SQLite-Datenbank. Passen Sie Secrets und Ports an Ihre Umgebung an; weitere Variablen siehe Kapitel „Umgebungsvariablen“.
|
||
|
||
## Docker-Deployment (Compose)
|
||
```yaml
|
||
# docker-compose.yml (Auszug)
|
||
services:
|
||
app:
|
||
image: ghcr.io/mboehmlaender/stackpulse:latest
|
||
ports:
|
||
- "4001:4001"
|
||
volumes:
|
||
- stackpulse_data:/app/backend/data
|
||
restart: unless-stopped
|
||
environment:
|
||
- PORTAINER_URL=https://portainer.example.com
|
||
- PORTAINER_API_KEY=xxxx
|
||
- SUPERUSER_USERNAME=admin
|
||
- SUPERUSER_EMAIL=admin@example.com
|
||
- SUPERUSER_PASSWORD=changeme
|
||
- SELF_STACK_ID=123
|
||
volumes:
|
||
stackpulse_data:
|
||
```
|
||
|
||
1. `docker compose up -d`
|
||
2. Das Frontend ist anschließend unter Port 4001 erreichbar.
|
||
3. Datenbank & Einstellungen liegen im benannten Volume `stackpulse_data`.
|
||
|
||
Damit bist du bereit für die tieferen Kapitel zu Architektur sowie Backend- und Frontend-Details.
|