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)

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

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:

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

# 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

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?

# 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:

  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:

  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)

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