develop - introduce local-setup

2026-08-27 18:01:16 +02:00
parent a8aa226875
commit 909029ca34
2 changed files with 386 additions and 0 deletions
@@ -0,0 +1,323 @@
+# Intranet lokal aufsetzen
+
+## 1. Docker installieren
+
+### Windows + WSL 2 — empfohlen
+
+PowerShell als Administrator:
+
+```powershell
+wsl --install -d Ubuntu-24.04
+wsl --update
+```
+
+Windows neu starten und prüfen:
+
+```powershell
+wsl -l -v
+```
+
+Ubuntu muss mit **WSL-Version 2** laufen.
+
+Falls `Ubuntu-24.04` über `wsl --install` nicht installiert werden kann, Ubuntu 24.04 alternativ über den Microsoft Store installieren.
+
+Danach **Docker Desktop for Windows** installieren und das WSL-2-Backend verwenden.
+
+In Docker Desktop:
+
+```text
+Settings → Resources → WSL Integration
+```
+
+Integration für Ubuntu aktivieren und in WSL testen:
+
+```bash
+docker --version
+docker compose version
+docker run --rm hello-world
+```
+
+> Docker Engine nicht zusätzlich innerhalb von WSL installieren, wenn Docker Desktop verwendet wird.
+>
+> Für bessere Dateisystem-Performance das Repository möglichst im WSL-Dateisystem ablegen, z. B. `~/src/intranet`, nicht unter `/mnt/c/...`.
+
+---
+
+### Linux — Ubuntu 24.04 LTS
+
+**1. Konfliktierende Pakete entfernen**
+
+```bash
+sudo apt remove docker.io docker-compose docker-compose-v2 docker-doc docker-buildx podman-docker containerd runc
+```
+
+**2. Voraussetzungen installieren**
+
+```bash
+sudo apt update
+sudo apt install ca-certificates curl -y
+```
+
+**3. Docker GPG-Key hinzufügen**
+
+```bash
+sudo install -m 0755 -d /etc/apt/keyrings
+sudo curl -fsSL https://download.docker.com/linux/ubuntu/gpg \
+  -o /etc/apt/keyrings/docker.asc
+sudo chmod a+r /etc/apt/keyrings/docker.asc
+```
+
+**4. Docker-Repository einrichten**
+
+```bash
+sudo tee /etc/apt/sources.list.d/docker.sources > /dev/null <<EOF
+Types: deb
+URIs: https://download.docker.com/linux/ubuntu
+Suites: $(. /etc/os-release && echo "${UBUNTU_CODENAME:-$VERSION_CODENAME}")
+Components: stable
+Architectures: $(dpkg --print-architecture)
+Signed-By: /etc/apt/keyrings/docker.asc
+EOF
+
+sudo apt update
+```
+
+**5. Docker Engine und Compose installieren**
+
+```bash
+sudo apt install docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin -y
+```
+
+**6. Docker aktivieren und testen**
+
+```bash
+sudo systemctl enable --now docker
+sudo docker run --rm hello-world
+docker compose version
+```
+
+**7. Optional: Docker ohne `sudo` verwenden**
+
+```bash
+sudo usermod -aG docker $USER
+```
+
+Danach ab- und wieder anmelden.
+
+> **Debian 13:** Das Projekt funktioniert ebenfalls unter Debian. Dafür das Docker-Repository entsprechend auf `linux/debian` umstellen:  
+> <https://docs.docker.com/engine/install/debian/>
+
+---
+
+### macOS
+
+1. **Docker Desktop for Mac** passend für Apple Silicon oder Intel installieren.
+2. Docker Desktop starten.
+3. Im Terminal testen:
+
+```bash
+docker --version
+docker compose version
+docker run --rm hello-world
+```
+
+Dokumentation:
+
+<https://docs.docker.com/desktop/setup/install/mac-install/>
+
+---
+
+## 2. Lokale Docker-Konfiguration
+
+Im Projektroot müssen folgende Dateien liegen:
+
+```text
+Dockerfile
+docker-compose.yml
+docker-compose.local.yml
+web/
+```
+
+Die produktive `docker-compose.yml` wird lokal **nicht** verwendet. Dadurch werden insbesondere folgende Produktionsbestandteile nicht gestartet:
+
+- `scheduler`
+- `dokploy-network`
+- Strato-SSH
+- produktive Scheduler-Secrets
+
+Die lokale Compose-Datei startet ausschließlich:
+
+- `web`
+- `db` (PostgreSQL)
+
+Sie verwendet denselben `Dockerfile` wie Produktion.
+
+Der Web-Container ist lokal unter `127.0.0.1:8080` erreichbar. PostgreSQL wird für pgAdmin unter `127.0.0.1:5432` freigegeben.
+
+Durch den Bind-Mount
+
+```text
+./web → /var/www/html
+```
+
+werden Änderungen an PHP, CSS und JavaScript ohne erneuten Image-Build sichtbar. Laufzeitdaten wie Profilbilder und Aushänge liegen weiterhin in lokalen Docker-Volumes.
+
+---
+
+## 3. Environment-Variablen anlegen
+
+Im Projektroot eine `.env` anlegen:
+
+```dotenv
+# PostgreSQL
+POSTGRES_VERSION=16
+DB_NAME=intranet
+DB_USER=intranet
+DB_PASSWORD=local-dev-password
+
+# Intranet
+INTRANET_FQDN=localhost:8080
+
+# Lokale Dummy-Werte für externe Dienste
+SMTP_HOST=127.0.0.1
+SMTP_PORT=1025
+SMTP_USER=local
+SMTP_PASSWORD=local
+ADMIN_EMAIL=local@example.invalid
+
+SMS_GATEWAY_URL=http://127.0.0.1:9
+HA_BASE_URL=http://127.0.0.1:9
+HA_TOKEN=local
+OPENWEATHER_API_KEY=local
+```
+
+### PostgreSQL-Version prüfen
+
+Lokal sollte möglichst dieselbe PostgreSQL-Major-Version wie in Produktion verwendet werden. Wir verwenden **PostgreSQL 18**.
+
+---
+
+## 4. Produktivdatenbank mit pgAdmin sichern
+
+In pgAdmin:
+
+1. Produktivserver öffnen.
+2. Unter **Databases** die Intranet-Datenbank rechtsklicken.
+3. **Backup…** auswählen.
+4. Datei außerhalb des Repositorys speichern, z. B. `intranet.dump`.
+5. **Format: Custom** wählen.
+6. Unter **Data Options → Do not save**:
+   - **Owner: Yes**
+   - **Privileges: Yes**
+7. **Include CREATE DATABASE statement: No** lassen.
+8. **Backup** starten.
+
+> Der Dump enthält Produktivdaten. Nicht committen oder weitergeben.
+
+---
+
+## 5. Lokale Datenbank starten
+
+Im Projektroot:
+
+```bash
+docker compose -f docker-compose.local.yml up -d db
+```
+
+Status prüfen:
+
+```bash
+docker compose -f docker-compose.local.yml ps
+```
+
+---
+
+## 6. Dump mit pgAdmin importieren
+
+In pgAdmin einen neuen Server registrieren:
+
+```text
+Host:                 localhost
+Port:                 5432
+Maintenance database: intranet
+Username:             intranet
+Password:             local-dev-password
+```
+
+Die Werte müssen den Angaben in `.env` entsprechen.
+
+Danach:
+
+1. Lokale Datenbank `intranet` rechtsklicken.
+2. **Restore…** auswählen.
+3. **Format: Custom**.
+4. `intranet.dump` auswählen.
+5. Unter **Data Options → Do not save**:
+   - **Owner: Yes**
+   - **Privileges: Yes**
+6. **Include CREATE DATABASE statement: No**
+7. **Clean before restore: No** beim ersten Import.
+8. **Restore** starten.
+
+Soll die lokale Datenbank später vollständig durch einen neuen Dump ersetzt werden:
+
+```bash
+docker compose -f docker-compose.local.yml down -v
+docker compose -f docker-compose.local.yml up -d db
+```
+
+Danach den Dump erneut importieren.
+
+> `down -v` löscht neben PostgreSQL auch die übrigen lokalen Intranet-Volumes.
+
+---
+
+## 7. Intranet starten
+
+```bash
+docker compose -f docker-compose.local.yml up -d --build
+```
+
+Aufrufen:
+
+<http://localhost:8080>
+
+Die Benutzer aus dem importierten Dump können anschließend für den Login verwendet werden.
+
+Die lokale Compose-Datei setzt `session.cookie_secure=0`, da lokal HTTP statt HTTPS verwendet wird.
+
+---
+
+## Entwicklung
+
+Status:
+
+```bash
+docker compose -f docker-compose.local.yml ps
+```
+
+Logs:
+
+```bash
+docker compose -f docker-compose.local.yml logs -f web
+```
+
+Nach Änderungen am `Dockerfile` neu bauen:
+
+```bash
+docker compose -f docker-compose.local.yml up -d --build
+```
+
+Normale Änderungen unter `web/` benötigen durch den Bind-Mount keinen Rebuild.
+
+Stoppen:
+
+```bash
+docker compose -f docker-compose.local.yml down
+```
+
+Komplett zurücksetzen:
+
+```bash
+docker compose -f docker-compose.local.yml down -v
+```