description

README.md

@@ -0,0 +1,195 @@
+# bizmatch-project
+
+Monorepo bestehend aus **Client** (`bizmatch-project/bizmatch`) und **Server/API** (`bizmatch-project/bizmatch-server`). Diese README führt dich vom frischen Clone bis zum laufenden System mit Produktivdaten im lokalen Dev-Setup.
+
+---
+
+## Voraussetzungen
+
+- **Node.js** ≥ 20.x (empfohlen LTS) und **npm**
+- **Docker** ≥ 24.x und **Docker Compose**
+- Netzwerkzugriff auf die lokalen Ports (Standard: App 3001, Postgres 5433)
+
+> **Hinweis zu Container-Namen/Ports**
+> In Beispielen wird der DB-Container als `bizmatchdb` angesprochen. Falls deine Compose andere Namen/Ports nutzt (z. B. `bizmatchdb-prod` oder Ports 5433/3001), passe die Befehle entsprechend an.
+
+---
+
+## Repository-Struktur (Auszug)
+
+```
+bizmatch-project/
+├─ bizmatch/                 # Client (Angular/React/…)
+├─ bizmatch-server/          # Server (NestJS + Postgres via Docker)
+│  ├─ docker-compose.yml
+│  ├─ env.prod               # Umgebungsvariablen (Beispiel)
+│  ├─ bizmatchdb-data-prod/  # (Volume-Pfad für Postgres-Daten)
+│  └─ initdb/                # (optional: SQL-Skripte für Erstinitialisierung)
+└─ README.md
+```
+
+---
+
+## 1) Client starten (Ordner `bizmatch`)
+
+```bash
+cd ~/git/bizmatch-project/bizmatch
+npm install
+npm start
+```
+
+- Der Client startet im Dev-Modus (Standardport: meist `http://localhost:4200` oder projektspezifisch; siehe `package.json`).
+- API-URL ggf. in den Client-Env-Dateien anpassen (z. B. `environment.ts`).
+
+---
+
+## 2) Server & Datenbank starten (Ordner `bizmatch-server`)
+
+### 2.1 .env-Datei anlegen
+
+Lege im Ordner `bizmatch-server` eine `.env` (oder `env.prod`) mit folgenden **Beispiel-/Dummy-Werten** an:
+
+```
+POSTGRES_DB=bizmatch
+POSTGRES_USER=bizmatch
+POSTGRES_PASSWORD=qG5LZhL7Y3
+DATABASE_URL=postgresql://bizmatch:qG5LZhL7Y3@postgres:5432/bizmatch
+
+OPENAI_API_KEY=sk-proj-3PVgp1dMTxnigr4nxgg
+```
+
+> **Wichtig:** Wenn du `DATABASE_URL` verwendest und dein Passwort Sonderzeichen wie `@ : / % # ?` enthält, **URL-encoden** (z. B. `@` → `%40`). Alternativ nur die Einzel-Variablen `POSTGRES_*` in der App verwenden.
+
+### 2.2 Docker-Services starten
+
+```bash
+cd ~/git/bizmatch-project/bizmatch-server
+# Erststart/Neustart der Services
+docker compose up -d
+```
+
+- Der Server-Container baut die App (NestJS) und startet auf Port **3001** (Host), intern **3000** (Container), sofern so in `docker-compose.yml` konfiguriert.
+- Postgres läuft im Container auf **5432**; per Port-Mapping meist auf **5433** am Host erreichbar (siehe `docker-compose.yml`).
+
+> Warte nach dem Start, bis in den DB-Logs „database system is ready to accept connections“ erscheint:
+>
+> ```bash
+> docker logs -f bizmatchdb
+> ```
+
+---
+
+## 3) Produktiv-Dump lokal importieren
+
+Falls du einen Dump aus der Produktion hast (Datei `prod.dump`), kannst du ihn in deine lokale DB importieren.
+
+### 3.1 Dump in den DB-Container kopieren
+
+```bash
+# im Ordner bizmatch-server
+docker cp prod.dump bizmatchdb:/tmp/prod.dump
+```
+
+> **Container-Name:** Falls dein DB-Container anders heißt (z. B. `bizmatchdb-prod`), ersetze den Namen im Befehl entsprechend.
+
+### 3.2 Restore ausführen
+
+```bash
+docker exec -it bizmatchdb \
+  sh -c 'pg_restore -U "$POSTGRES_USER" --clean --no-owner -d "$POSTGRES_DB" /tmp/prod.dump'
+```
+
+- `--clean` löscht vorhandene Objekte vor dem Einspielen
+- `--no-owner` ignoriert Besitzer/Role-Bindungen (praktisch für Dev)
+
+### 3.3 Smoke-Test: DB erreichbar?
+
+```bash
+# Ping/Verbindung testen (pSQL muss im Container verfügbar sein)
+docker exec -it bizmatchdb \
+  sh -lc 'PGPASSWORD="$POSTGRES_PASSWORD" psql -h /var/run/postgresql -U "$POSTGRES_USER" -d "$POSTGRES_DB" -c "select current_user, now();"'
+```
+
+---
+
+## 4) Häufige Probleme & Lösungen
+
+### 4.1 `password authentication failed for user "bizmatch"`
+
+- Prüfe, ob die Passwortänderung **in der DB** erfolgt ist (Env-Änderung allein genügt nicht, wenn das Volume existiert).
+- Passwort in Postgres setzen:
+
+  ```bash
+  docker exec -u postgres -it bizmatchdb \
+    psql -d postgres -c "ALTER ROLE bizmatch WITH LOGIN PASSWORD 'NEUES_PWD';"
+  ```
+
+- App-Umgebung (`.env`) anpassen und App neu starten:
+
+  ```bash
+  docker compose restart app
+  ```
+
+- Bei Nutzung von `DATABASE_URL`: Sonderzeichen **URL-encoden**.
+
+### 4.2 Container-Hostnamen stimmen nicht
+
+- Innerhalb des Compose-Netzwerks ist der **Service-Name** der Host (z. B. `postgres` oder `postgres-prod`). Achte darauf, dass `DB_HOST`/`DATABASE_URL` dazu passen.
+
+### 4.3 Dump/Restore vs. Datenverzeichnis-Kopie
+
+- **Empfehlung:** `pg_dump/pg_restore` für Prod→Dev.
+- Ganze Datenverzeichnisse (Volume) nur **bei gestoppter** DB und **identischer Postgres-Major-Version** kopieren.
+
+### 4.4 Ports
+
+- API nicht erreichbar? Prüfe Port-Mapping in `docker-compose.yml` (z. B. `3001:3000`) und Firewall.
+- Postgres-Hostport (z. B. `5433`) gegen Client-Konfiguration prüfen.
+
+---
+
+## 5) Nützliche Befehle (Cheatsheet)
+
+```bash
+# Compose starten/stoppen
+cd ~/git/bizmatch-project/bizmatch-server
+docker compose up -d
+docker compose stop
+
+# Logs
+docker logs -f bizmatchdb
+docker logs -f bizmatch-app
+
+# Shell in Container
+docker exec -it bizmatchdb sh
+
+# Datenbankbenutzer-Passwort ändern
+docker exec -u postgres -it bizmatchdb \
+  psql -d postgres -c "ALTER ROLE bizmatch WITH LOGIN PASSWORD 'NEUES_PWD';"
+
+# Dump aus laufender DB (vom Host, falls Port veröffentlicht ist)
+PGPASSWORD="$POSTGRES_PASSWORD" \
+pg_dump -h 127.0.0.1 -p 5433 -U "$POSTGRES_USER" -d "$POSTGRES_DB" \
+  -F c -Z 9 -f ./prod.dump
+```
+
+---
+
+## 6) Sicherheit & Datenschutz
+
+- Lege **keine echten Secrets** (API-Keys, Prod-Passwörter) im Repo ab. Nutze `.env`-Dateien außerhalb der Versionskontrolle oder einen Secrets-Manager.
+- Bei Produktivdaten in Dev: **Anonymisierung** (Masking) für personenbezogene Daten erwägen.
+
+---
+
+## 7) Erweiterungen (optional)
+
+- **Init-Skripte**: Lege SQL-Dateien in `bizmatch-server/initdb/` ab, um beim Erststart Benutzer/Schema anzulegen.
+- **Multi-Stage Dockerfile** für den App-Container (schnellere, reproduzierbare Builds ohne devDependencies).
+- **Makefile/Skripte** für häufige Tasks (z. B. `make db-backup`, `make db-restore`).
+
+---
+
+## 8) Support
+
+Bei Fragen zu Setup, Dumps oder Container-Namen/Ports: Logs und Compose-Datei prüfen, anschließend die oben beschriebenen Tests (DNS/Ports, psql) durchführen. Anschließend Issue/Notiz anlegen mit Logs & `docker-compose.yml`-Ausschnitt.