196 lines
6.3 KiB
Markdown
196 lines
6.3 KiB
Markdown
# 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.
|