intranet/README.md

# Intranet lokal aufsetzen

# 0. Git installieren und Repository klonen

Bevor das Intranet lokal eingerichtet werden kann, muss Git installiert und das Repository heruntergeladen werden.

## Windows

Git for Windows kann direkt über `winget` installiert werden:

```powershell
winget install --id Git.Git -e --source winget
```

Alternativ kann **Git for Windows** über https://git-scm.com/install/windows heruntergeladen und installiert werden.

Nach der Installation PowerShell, Windows Terminal oder Git Bash neu öffnen und prüfen:

```bash
git --version
```

> Wird das Projekt anschließend mit Docker über WSL 2 verwendet, empfiehlt es sich, auch das Repository innerhalb des WSL-Dateisystems zu klonen, z. B. unter `~/src/intranet`.

### macOS

Falls Homebrew noch nicht installiert ist, die Installationsanleitung unter https://brew.sh/ verwenden.

Git über Homebrew installieren:

```bash
brew install git
```

Danach prüfen:

```bash
git --version
```

## Git konfigurieren

Beim ersten Einrichten den eigenen Namen und die E-Mail-Adresse für Commits hinterlegen:

```bash
git config --global user.name "Vorname Nachname"
git config --global user.email "name@example.com"
```

## Repository klonen

### macOS / Linux / WSL

```bash
cd ~/Documents
git clone https://git.pelpino.de/NAK-Reinickendorf/intranet.git
cd intranet
```

### Windows

```powershell
cd $HOME\Documents
git clone https://git.pelpino.de/NAK-Reinickendorf/intranet.git
cd intranet
```

Beim Klonen über HTTPS können Benutzername und Personal Access Token abgefragt werden. Als Passwort wird in diesem Fall der **Token**, nicht das normale Account-Passwort verwendet.

## HTTPS-Zugangsdaten speichern

### macOS

```bash
git config --global credential.helper osxkeychain
```

Beim nächsten Zugriff einmal Benutzername und Token eingeben. Anschließend werden die Zugangsdaten im macOS-Schlüsselbund gespeichert.

### Windows

Git for Windows enthält den **Git Credential Manager**. Bei der ersten Authentifizierung können die Zugangsdaten darüber sicher gespeichert werden.

## Repository prüfen

```bash
git status
git remote -v
```

Das Remote Repository sollte auf folgende Adresse verweisen:

```text
https://git.pelpino.de/NAK-Reinickendorf/intranet.git
```

---

## 2. 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
```

Falls `docker run` mit

```text
permission denied while trying to connect to the docker API at unix:///var/run/docker.sock
```

abbricht, zunächst prüfen:

```bash
ls -l /var/run/docker.sock
id
getent group docker
```

Ist der Benutzer bereits Mitglied der Gruppe `docker`, die Gruppe aber bei `id` noch nicht aufgeführt, wurde die Gruppenmitgliedschaft von der aktuellen Shell noch nicht übernommen. Dann entweder:

```bash
newgrp docker
```

ausführen oder WSL vollständig neu starten. Dazu in PowerShell:

```powershell
wsl --shutdown
```

Danach Ubuntu erneut öffnen und `docker run --rm hello-world` wiederholen.

> 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

> **Wichtig für WSL-Nutzer:**
> Wenn Ubuntu unter Windows über WSL 2 läuft und Docker Desktop verwendet wird, **nicht** mit diesem Abschnitt weitermachen. Dieser Abschnitt ist nur für eigenständige Linux-Installationen vorgesehen.

**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 <<EOF2
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
EOF2

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/

---

## 3. Lokale Docker-Konfiguration

Im Projektroot müssen folgende Dateien liegen:

```text
Dockerfile
docker-compose.yml
docker-compose.local.yml
web/
worker/
docker/
```

Die `docker-compose.local.yml` bildet die Anwendungsdienste der produktiven `docker-compose.yml` lokal ab und ergänzt die Datenbank. Lokal werden damit gestartet:

* `web`
* `scheduler`
* `db` (PostgreSQL 18 mit pgvector)

Das externe `dokploy-network` wird lokal nicht benötigt. Alle drei Container verwenden stattdessen das lokale Compose-Netzwerk `app`. `web` und `scheduler` greifen über `DB_HOST=db` direkt auf den lokalen PostgreSQL-Container zu.

Der Web-Container ist unter `127.0.0.1:8080` erreichbar. PostgreSQL wird für pgAdmin unter `127.0.0.1:5432` freigegeben.

Für die Datenbank wird das Image `pgvector/pgvector:pg18` verwendet, weil der Produktiv-Dump die PostgreSQL-Erweiterung `vector` benötigt. PostgreSQL 18 verwendet für persistente Daten den Mount-Punkt:

```text
/var/lib/postgresql
```

Nicht verwenden:

```text
/var/lib/postgresql/data
```

Durch den Bind-Mount

```text
./web → /var/www/html
```

werden Änderungen an PHP, CSS und JavaScript ohne erneuten Image-Build sichtbar. Laufzeitdaten wie Profilbilder, Aushänge, Scheduler-Zustand und generierte Kalenderdateien liegen weiterhin in lokalen Docker-Volumes.

---

## 4. Environment-Variablen anlegen

Im Projektroot eine `.env` anlegen. Werte, die lokal nicht benötigt oder noch nicht bekannt sind, bleiben leer.

```dotenv
# PostgreSQL
DB_HOST=
DB_PORT=5432
DB_NAME=intranet
DB_USER=intranet
DB_PASSWORD=local-dev-password

# Intranet
INTRANET_FQDN=localhost:8080

# SMTP / Benachrichtigungen
SMTP_HOST=
SMTP_PORT=
SMTP_USER=
SMTP_PASSWORD=
ADMIN_EMAIL=
SMS_GATEWAY_URL=

# Dashboard / externe APIs
HA_BASE_URL=
HA_TOKEN=
OPENWEATHER_API_KEY=
VBB_ACCESS_ID=
VBB_API_BASE_URL=https://vbb.demo.hafas.cloud/api/fahrinfo/latest

# Contentpanel / Aushang-Formatüberführung
OLLAMA_GATEWAY_URL=https://ollama.pelpino.de
OLLAMA_API_KEY=
OLLAMA_AUTH_HEADER=Authorization
OLLAMA_MODEL=qwen3.8:27b
OLLAMA_API_STYLE=openai
OLLAMA_TIMEOUT_SECONDS=600
CONTENTPANEL_JOB_TIMEOUT_SECONDS=3600
OLLAMA_MAX_INPUT_CHARS=45000
OLLAMA_CONTEXT_LENGTH=32768
CONTENTPANEL_MAX_INPUT_PAGES=10
CONTENTPANEL_MAX_RENDERED_PAGES=10
CONTENTPANEL_RENDER_SCALE=3

# CKalender / Scheduler
CKAL_USERNAME=
CKAL_PASSWORD=
CKAL_CALENDAR_URL=
CALENDAR_INTERVAL_SECONDS=60

# Strato-Synchronisation
STRATO_SYNC_ENABLED=false
STRATO_SSH_HOST=
STRATO_SSH_PORT=
STRATO_SSH_USER=
STRATO_REMOTE_PATH=
STRATO_SSH_PRIVATE_KEY=
STRATO_KNOWN_HOSTS=

# Brandschutz
BRANDSCHUTZ_MAIL_ENABLED=false
```

Funktionen, die einen externen Dienst benötigen, funktionieren erst, wenn die zugehörigen Werte gesetzt sind.

> Lokal sollte möglichst dieselbe PostgreSQL-Major-Version wie in Produktion verwendet werden. Wir verwenden **PostgreSQL 18**.

---

## 5. 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.
9. Läuft pgAdmin im Browser auf einem entfernten Server, kann die Backup-Datei anschließend über **Tools → Storage Manager** heruntergeladen werden.

> Der Dump enthält Produktivdaten. Nicht committen, weitergeben oder in ungeschützten Cloud-Ordnern speichern.

---

## 6. 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
```

Der Datenbank-Container sollte nach einigen Sekunden den Status `healthy` anzeigen.

---

## 7. Dump mit pgAdmin importieren

### pgAdmin 4 installieren

Falls pgAdmin 4 noch nicht installiert ist, kann es lokal als Desktop-Anwendung installiert werden.

* **Windows:** pgAdmin-Installer herunterladen und ausführen.
* **macOS:** pgAdmin-Disk-Image herunterladen, öffnen und die Anwendung installieren.
* **Ubuntu/Linux:** pgAdmin kann über das offizielle APT-Repository installiert werden; für die lokale Nutzung reicht `pgadmin4-desktop`.

Die Installationspakete und Anleitungen sind unter https://www.pgadmin.org/download/ verfügbar.

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 or tar** wählen.
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.

> **Hinweis:** Soll die lokale Datenbank später vollständig durch einen neuen Dump ersetzt werden, kann das lokale Setup zurückgesetzt werden: `docker compose -f docker-compose.local.yml down -v`,
`docker compose -f docker-compose.local.yml up -d db`. Danach den Dump erneut importieren.

> **Achtung:** `down -v` löscht nicht nur PostgreSQL, sondern auch alle übrigen lokalen Intranet-Volumes, z. B. Profilbilder, Aushänge und andere Laufzeitdaten. Nur verwenden, wenn diese Daten bewusst verworfen werden sollen.

---

## 8. Intranet starten

```bash
docker compose -f docker-compose.local.yml up -d --build
```

Status prüfen:

```bash
docker compose -f docker-compose.local.yml ps
```

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

### Nach einem Neustart starten

Nach einem Neustart von Windows oder macOS zuerst **Docker Desktop** starten und warten, bis Docker bereit ist.

Unter einer eigenständigen Linux-Installation sicherstellen, dass der Docker-Dienst läuft.

Danach im Projektroot die lokalen Container starten:

```bash
docker compose -f docker-compose.local.yml up -d
```

Falls sich das `Dockerfile` seit dem letzten Start geändert hat oder die Images neu gebaut werden sollen:

```bash
docker compose -f docker-compose.local.yml up -d --build
```

Anschließend kann das Intranet wieder unter http://localhost:8080 aufgerufen werden.

### Status prüfen

```bash
docker compose -f docker-compose.local.yml ps
```

### Web-Logs anzeigen

```bash
docker compose -f docker-compose.local.yml logs -f web
```

### Datenbank-Logs anzeigen

```bash
docker compose -f docker-compose.local.yml logs -f db
```

### Änderungen an PHP, CSS und JavaScript

Änderungen unter `web/` werden durch den Bind-Mount direkt in den laufenden Container übernommen. Ein Rebuild ist normalerweise nicht notwendig. Nach dem Speichern reicht in der Regel ein Reload im Browser.

### Änderungen am Dockerfile

Nach Änderungen am `Dockerfile` neu bauen:

```bash
docker compose -f docker-compose.local.yml up -d --build
```

### Stoppen

```bash
docker compose -f docker-compose.local.yml down
```

Die Docker-Volumes bleiben dabei erhalten.

### Komplett zurücksetzen

```bash
docker compose -f docker-compose.local.yml down -v
```

> **Achtung:** Dabei werden alle lokalen Docker-Volumes des Projekts gelöscht, einschließlich der lokalen PostgreSQL-Datenbank.