description
This commit is contained in:
parent
351b560bcc
commit
4fa24c8f3d
|
|
@ -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.
|
||||
Binary file not shown.
Loading…
Reference in New Issue