TeamVis Release
142 lines
5.1 KiB
Markdown
142 lines
5.1 KiB
Markdown
# TeamVis Self-Hosting — Quickstart (von der nackten VM bis live)
|
||
|
||
Diese Anleitung führt von einer **komplett frischen Linux-VM** bis zur
|
||
laufenden TeamVis-Instanz. Sie nutzt den Ein-Schritt-Installer
|
||
`deploy/selfhost/install.sh` (Hintergrund & manuelle Varianten:
|
||
`deploy/selfhost/README.md`, externe Supabase: `docs/NEUKUNDE.md`).
|
||
|
||
Zwei Betriebsarten zur Auswahl (fragt der Installer ab):
|
||
|
||
- **Modus 2 — alles mitinstallieren** (empfohlen für „nur eine VM"): TeamVis
|
||
**und** eine schlanke Supabase laufen als Container auf derselben VM, unter
|
||
**einer Domain**. Kein externes Supabase nötig.
|
||
- **Modus 1 — eigene/bestehende Supabase**: du hast schon ein Supabase-Projekt
|
||
(Cloud oder self-hosted); es läuft nur die App.
|
||
|
||
Diese Anleitung beschreibt **Modus 2** (der Komplettfall).
|
||
|
||
---
|
||
|
||
## 0. Voraussetzungen
|
||
|
||
**Du brauchst vorab:**
|
||
|
||
| Was | Details |
|
||
|---|---|
|
||
| **VM** | Ubuntu 22.04+/Debian 12+, **2 GB RAM**+ (Modus 2 ≈ 1–1,5 GB), ~10 GB Disk. Root- bzw. sudo-Zugang. |
|
||
| **Domain** | z. B. `team.kunde.de`, mit **DNS-A-Record auf die öffentliche IP der VM**. Caddy holt das TLS-Zertifikat dann automatisch. |
|
||
| **Offene Ports** | eingehend **80 und 443** (Let's Encrypt + Web). |
|
||
| **Image-Pull-Token** | ein **Token** für die Registry `git.zfx.services` — **vom TeamVis-Anbieter**. Nur fürs **Container-Image**. Das Installer-Bundle ist öffentlich (kein Token). |
|
||
|
||
> So ist die Auslieferung getrennt: Das **Bundle** (Installer + Migrationen, kein
|
||
> Quellcode) liegt in einem **öffentlichen** Repo und ist ohne Login klonbar. Nur
|
||
> das private **Container-Image** braucht den Pull-Token. Der App-Quellcode bleibt
|
||
> in jedem Fall unzugänglich. (Anbieter-Details: `docs/DISTRIBUTION.md`.)
|
||
|
||
---
|
||
|
||
## 1. Grundpakete installieren
|
||
|
||
Auf der frischen VM (als root oder mit `sudo`):
|
||
|
||
```bash
|
||
# Docker + Compose-Plugin
|
||
curl -fsSL https://get.docker.com | sh
|
||
sudo usermod -aG docker "$USER" # danach einmal aus-/einloggen (oder: newgrp docker)
|
||
|
||
# Node 20 + git + openssl
|
||
curl -fsSL https://deb.nodesource.com/setup_20.x | sudo bash -
|
||
sudo apt-get install -y nodejs git openssl
|
||
|
||
# Kontrolle
|
||
docker --version && docker compose version && node --version
|
||
```
|
||
|
||
---
|
||
|
||
## 2. An der Registry anmelden (Token)
|
||
|
||
Benutzer ist `teamvis-pull`, Passwort der Token vom Anbieter:
|
||
|
||
```bash
|
||
docker login git.zfx.services
|
||
# Benutzer: teamvis-pull · Passwort: <Token>
|
||
```
|
||
|
||
---
|
||
|
||
## 3. Installer-Bundle holen
|
||
|
||
Das Bundle ist **öffentlich** — kein Login nötig:
|
||
|
||
```bash
|
||
git clone https://git.zfx.services/zfx-public/teamvis-selfhost.git
|
||
cd teamvis-selfhost
|
||
```
|
||
|
||
(Enthält Installer, Helfer-Skripte und Migrationen — **keinen** App-Quellcode.
|
||
Die App selbst kommt als fertiges Image aus der Registry, wird also nicht
|
||
gebaut. Kein git? Stattdessen das Release-Tarball des Anbieters entpacken.)
|
||
|
||
---
|
||
|
||
## 4. Installer ausführen
|
||
|
||
```bash
|
||
bash deploy/selfhost/install.sh
|
||
```
|
||
|
||
Der Installer fragt der Reihe nach:
|
||
|
||
1. **Kurzname** der Instanz (z. B. `kunde`) — nur für Verzeichnis/Compose-Name.
|
||
2. **Domain** der App (`team.kunde.de`).
|
||
3. **Image-Version** (Default = aktuelle Version, einfach Enter).
|
||
4. **Admin-E-Mail** + **Name** (der erste Backend-Login).
|
||
5. **Zielverzeichnis** (Default: `./kunde`).
|
||
6. **SMTP** (optional — leer lassen ist ok; dann landen Login-/Magic-Links nur
|
||
im Container-Log statt im Postfach. Lässt sich später in der `.env` nachtragen).
|
||
7. **Datenbank-Modus** → hier **`2`** wählen.
|
||
8. Am Ende: **Admin-Passwort** (mind. 10 Zeichen, verdeckt).
|
||
|
||
Danach erledigt das Skript automatisch: Schlüssel/Secrets erzeugen, `.env` +
|
||
`docker-compose.yml` + `Caddyfile` schreiben, Datenbank starten,
|
||
Rollen-Bootstrap + Rechte, Schema einspielen, App + Caddy starten, ersten Admin
|
||
anlegen. Dauer: wenige Minuten (Image-Download).
|
||
|
||
---
|
||
|
||
## 5. Erster Login & Abnahme
|
||
|
||
1. `https://team.kunde.de/admin/login` öffnen → mit Admin-E-Mail + Passwort
|
||
anmelden (beim ersten Login wird ein neues Passwort gesetzt).
|
||
2. **Admin → Branding**: Firmenname, Logo, Farben, Impressum.
|
||
3. **Admin → Mitarbeiter**: erste Karte anlegen (oder CSV-Import).
|
||
4. **Admin → Funktionen**: weitere Module gestaffelt freischalten — eine frische
|
||
Instanz startet bewusst nur mit den **Visitenkarten**.
|
||
|
||
**Smoke-Test:**
|
||
- [ ] `https://team.kunde.de/<slug>` zeigt eine Karte (ohne Login)
|
||
- [ ] vCard-Download `…/api/vcard/<slug>` liefert `.vcf`
|
||
- [ ] Foto-Upload im Backend erscheint auf der Karte
|
||
- [ ] (mit SMTP) Self-Service-Portal verschickt einen Login-Code
|
||
|
||
---
|
||
|
||
## 6. Betrieb
|
||
|
||
- **Updates:** Image-Tag in `kunde/docker-compose.yml` bumpen, bei Minor-Sprüngen
|
||
vorher die neue(n) Migration(en) einspielen → `docker compose pull && up -d`.
|
||
Details: `docs/NEUKUNDE.md` §7.
|
||
- **Backup (wichtig, jetzt liegt die DB bei dir):** das Postgres-Volume
|
||
(`db-data`) **und** `kunde/volumes/storage` sichern. Die `.env` gehört in einen
|
||
Passwort-Safe (enthält alle Secrets), **nicht** ins Backup-Repo.
|
||
|
||
---
|
||
|
||
## Wenn etwas klemmt
|
||
|
||
- `docker compose pull` schlägt fehl → `docker login git.zfx.services` nachholen.
|
||
- TLS kommt nicht → DNS-A-Record + offene Ports 80/443 prüfen (Caddy braucht
|
||
beide für Let's Encrypt).
|
||
- Logs ansehen: `cd kunde && docker compose logs -f app` bzw. `caddy`.
|