diff --git a/README.md b/README.md new file mode 100644 index 0000000..14bc14d --- /dev/null +++ b/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. diff --git a/bizmatch-server/prod.dump b/bizmatch-server/prod.dump new file mode 100755 index 0000000..035fc81 Binary files /dev/null and b/bizmatch-server/prod.dump differ