Merge pull request 'bugfix - tutorial fixed' (#5) from dev into main

Reviewed-on: #5
Reviewed-by: Samuel Bias <samuel@bias-mail.de>

README.md

@@ -1,6 +1,102 @@
 # Intranet lokal aufsetzen
 
-## 1. Docker installieren
+# 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
 
@@ -70,14 +166,14 @@ 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
+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
-EOF
+EOF2
 
 sudo apt update
 ```
@@ -127,7 +223,7 @@ Dokumentation:
 
 ---
 
-## 2. Lokale Docker-Konfiguration
+## 3. Lokale Docker-Konfiguration
 
 Im Projektroot müssen folgende Dateien liegen:
 
@@ -148,12 +244,26 @@ Die produktive `docker-compose.yml` wird lokal **nicht** verwendet. Dadurch werd
 Die lokale Compose-Datei startet ausschließlich:
 
 - `web`
-- `db` (PostgreSQL)
+- `db` (PostgreSQL 18 mit pgvector)
 
 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.
 
+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
@@ -164,13 +274,13 @@ werden Änderungen an PHP, CSS und JavaScript ohne erneuten Image-Build sichtbar
 
 ---
 
-## 3. Environment-Variablen anlegen
+## 4. Environment-Variablen anlegen
 
 Im Projektroot eine `.env` anlegen:
 
 ```dotenv
 # PostgreSQL
-POSTGRES_VERSION=16
+POSTGRES_VERSION=18
 DB_NAME=intranet
 DB_USER=intranet
 DB_PASSWORD=local-dev-password
@@ -191,13 +301,15 @@ HA_TOKEN=local
 OPENWEATHER_API_KEY=local
 ```
 
+Die `.env` darf keine produktiven Secrets enthalten und sollte nicht ins Repository committed werden.
+
 ### 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
+## 5. Produktivdatenbank mit pgAdmin sichern
 
 In pgAdmin:
 
@@ -212,11 +324,13 @@ In pgAdmin:
 7. **Include CREATE DATABASE statement: No** lassen.
 8. **Backup** starten.
 
-> Der Dump enthält Produktivdaten. Nicht committen oder weitergeben.
+Wenn pgAdmin im Browser auf einem entfernten Server läuft, wird die Backup-Datei serverseitig gespeichert. Sie kann anschließend über **Tools → Storage Manager** heruntergeladen werden.
+
+> Der Dump enthält Produktivdaten. Nicht committen, weitergeben oder in ungeschützten Cloud-Ordnern speichern.
 
 ---
 
-## 5. Lokale Datenbank starten
+## 6. Lokale Datenbank starten
 
 Im Projektroot:
 
@@ -230,9 +344,17 @@ Status prüfen:
 docker compose -f docker-compose.local.yml ps
 ```
 
+Der Datenbank-Container sollte nach einigen Sekunden den Status `healthy` anzeigen.
+
+Optional kann geprüft werden, ob pgvector verfügbar ist:
+
+```bash
+docker exec -it intranet-local-db-1 psql -U intranet -d intranet -c "CREATE EXTENSION IF NOT EXISTS vector;"
+```
+
 ---
 
-## 6. Dump mit pgAdmin importieren
+## 7. Dump mit pgAdmin importieren
 
 In pgAdmin einen neuen Server registrieren:
 
@@ -250,16 +372,18 @@ Danach:
 
 1. Lokale Datenbank `intranet` rechtsklicken.
 2. **Restore…** auswählen.
-3. **Format: Custom**.
+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**
+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:
+Der Restore sollte ohne Fehler zur fehlenden Extension `vector` durchlaufen. Falls `pg_restore` mit `extension "vector" is not available` abbricht, prüfen, ob in `docker-compose.local.yml` tatsächlich `pgvector/pgvector:pg18` verwendet wird.
+
+Soll die lokale Datenbank später vollständig durch einen neuen Dump ersetzt werden, kann das lokale Setup zurückgesetzt werden:
 
 ```bash
 docker compose -f docker-compose.local.yml down -v
@@ -268,16 +392,22 @@ 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.
+> **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.
 
 ---
 
-## 7. Intranet starten
+## 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>
@@ -290,34 +420,50 @@ Die lokale Compose-Datei setzt `session.cookie_secure=0`, da lokal HTTP statt HT
 
 ## Entwicklung
 
-Status:
+### Status prüfen
 
 ```bash
 docker compose -f docker-compose.local.yml ps
 ```
 
-Logs:
+### 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
 ```
 
-Normale Änderungen unter `web/` benötigen durch den Bind-Mount keinen Rebuild.
+### Stoppen
-
-Stoppen:
 
 ```bash
 docker compose -f docker-compose.local.yml down
 ```
 
-Komplett zurücksetzen:
+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.

docker-compose.local.yml

@@ -36,7 +36,7 @@ services:
       - calendar_pdf:/var/www/html/pdf
 
   db:
-    image: postgres:${POSTGRES_VERSION:-16}
+    image: pgvector/pgvector:pg18
     ports:
       - "127.0.0.1:5432:5432"
     environment:
@@ -45,7 +45,7 @@ services:
       POSTGRES_USER: ${DB_USER:?set DB_USER in .env}
       POSTGRES_PASSWORD: ${DB_PASSWORD:?set DB_PASSWORD in .env}
     volumes:
-      - postgres_data:/var/lib/postgresql/data
+      - postgres_data:/var/lib/postgresql
     healthcheck:
       test: ["CMD-SHELL", "pg_isready -U \"$${POSTGRES_USER}\" -d \"$${POSTGRES_DB}\""]
       interval: 5s