% Ghid de instalare și operare — DiDi Lot 2 (Backend)
% PNRR DIGI150 · contract 11.1.i3.c9

---

# 1. Precondiții

## Software
- **Docker** ≥ 24 și **Docker Compose v2** (`docker compose version`).
- `git`, `curl`, `bash`. Fără dependențe de rețea externă pentru pornirea backend-ului.

## Hardware (recomandat, per mașină backend)
- 8 vCPU, 16 GB RAM, 50 GB disc liber (fără modelele AI, care rulează pe Lotul 1).

## Rețea
- Backendul rulează self-contained. Pentru analiza AI reală, mașina trebuie să poată accesa
  serviciile **Lotului 1** (platforma AI) prin URL-urile configurate în `.env` (vezi §5).

---

# 2. Conținutul arhivei livrate

```
backend/
├── production/
│   ├── build-local.sh          ← scriptul principal de instalare
│   └── .env.example            ← șablon variabile (Redis/Keycloak/Kong)
├── services/
│   ├── data-layer/             ← PostgreSQL + Redis + RabbitMQ + MinIO + Keycloak
│   │   └── didiDatabase/DIDI_full_export_2026-07-02.sql   ← seed baza de date
│   ├── gateway-auth-layer/     ← Kong + Keycloak (config + realm)
│   └── orchestration-layer/
│       ├── agent-v3/           ← motorul de analiză (+ .env.example)
│       └── didiFramework/      ← CRUD parametri (+ .env.example)
├── admin-dashboard/            ← interfața administrativă React
├── observability/              ← Prometheus/Grafana/Loki/OTel
└── docs/                       ← acest ghid + arhitectură + raport testare
```

> **Seed-ul bazei de date** (`DIDI_full_export_2026-07-02.sql`, ~23 MB) trebuie să fie prezent
> în `services/data-layer/didiDatabase/` înainte de instalare. Conține schema completă +
> datele + toate migrațiile.

---

# 3. Pași de instalare

## Pasul 1 — Pregătește fișierele `.env`

Fiecare serviciu are un `.env.example`. Copiază-l în `.env` și completează secretele
(valorile marcate `CHANGE_ME`):

```bash
cd backend
cp services/orchestration-layer/agent-v3/.env.example services/orchestration-layer/agent-v3/.env
cp services/orchestration-layer/didiFramework/.env.example services/orchestration-layer/didiFramework/.env
cp admin-dashboard/.env.example admin-dashboard/.env
cp production/.env.example production/.env
```

Secrete de completat în `agent-v3/.env`: cheile LLM (`OPENROUTER_API_KEY`, `OPENAI_API_KEY`,
`GROQ_API_KEY`, opțional `ANTHROPIC_API_KEY`, `GOOGLE_API_KEY`), tokenul Whisper
(`M17_WHISPER_TOKEN`), cheile MinIO. **URL-urile Lotului 1** se setează tot aici (vezi §5).

## Pasul 2 — Rulează scriptul de instalare

```bash
cd backend/production
chmod +x build-local.sh
./build-local.sh [hostname]        # implicit: hostname-ul mașinii de deployment
```

Scriptul ridică toată stiva în ordinea corectă:
1. rețea Docker `didi-network`;
2. stratul de date (PostgreSQL + **import automat al seed-ului** la primul boot, Redis,
   RabbitMQ, MinIO, Keycloak);
3. Kong (gateway DBless);
4. didiFramework + **sincronizarea Redis** (încarcă parametrii din PostgreSQL);
5. agent-v3 + cei 13 workeri;
6. admin dashboard.

Durata tipică: 5–10 minute (majoritatea = build-ul imaginilor Docker + `npm install`).

## Pasul 3 — Verifică

La final, scriptul afișează un rezumat de health checks. Verificare manuală:

```bash
docker exec didi-postgres pg_isready -U bos_interface
docker exec didi-framework wget -qO- http://127.0.0.1:3005/health
docker exec didi-agent-v3 wget -qO- http://localhost:24803/api/v3/health
docker exec didi-cache redis-cli -a redis123 --no-auth-warning keys 'didi:framework:*' | wc -l   # aștept 8
```

---

# 4. Ce pornește (containere)

| Container | Rol | Port |
|---|---|---|
| `didi-postgres` | PostgreSQL 17 (baza de date principală) | 5432 |
| `didi-cache` | Redis 7 | 6379 |
| `staging-dataLayer-rabbitmq` | RabbitMQ 3.12 | 5672 / 15672 |
| `staging-dataLayer-minio` | MinIO (S3) | 9000 / 9001 |
| `didi-keycloak` | Keycloak (OIDC) | 28080 (`/auth`) |
| `didi-kong` | API Gateway (DBless) | 18000 / 18001 / 18443 |
| `didi-framework` | CRUD parametri | 3005 (intern) |
| `didi-agent-v3` | motor de analiză | 24803 |
| `agent-v3-worker-*` (×11) | workeri componente | — |
| `verdict-aggregator` (×2) | agregare verdict | — |
| `didi-admin-local` | admin dashboard | 3081 / 3001 |

---

# 5. Configurarea Lotului 1 (platforma AI)

Agent V3 apelează serviciile AI prin URL-uri din `agent-v3/.env`, blocul „Lot 1 — Platforma
AI". **Pe mașina unde e instalat și Lotul 1, se ajustează doar host-urile:**

```
LLM_ROUTER_URL=http://<host-lot1>:14011          # modele LLM text + OCR
VISION_LLM_URL=http://<host-lot1>:14011           # analiză imagine
DIDI_BRAIN_URL=http://<host-lot1>:8090            # brain (verification cache + RAG)
VIDEO_ANALYSIS_URL=http://<host-lot1>:54600       # deepfake video
EXTRACTORS_URL=http://<host-lot1>:54400           # EXIF/ELA/NER/YOLO/OCR
FORENSIC_API_URL=http://<host-lot1>:8080          # forensic
M17_WHISPER_URL=http://<host-lot1>:54300/v1/audio/transcriptions   # transcriere
M17_WEB_API_URL=http://<host-lot1>:51100          # web search
DOMAIN_CHECK_API_URL=http://<host-lot1>:11000/api/v1/check/check    # domain check
```

Dacă Lotul 1 rulează pe **aceeași rețea Docker**, se pot folosi numele de container
(ex. `http://didiAI-extractors:54400`). Dacă e pe **alt host**, se pune IP-ul.

După modificarea `.env`, se reconstruiește agent-v3:
```bash
cd backend/services/orchestration-layer/agent-v3 && docker compose up -d --build
```

---

# 6. Operare curentă

## Resincronizarea parametrilor în Redis (după orice modificare de config)
```bash
docker exec didi-framework wget -qO- --post-data='' http://127.0.0.1:3005/api/sync-redis
```

## Reconstruirea unui serviciu
```bash
# agent-v3 + workeri
cd backend/services/orchestration-layer/agent-v3 && docker compose up -d --build
# framework
cd backend/services/orchestration-layer/didiFramework && docker compose up -d --build
```

## Scalarea workerilor
```bash
cd backend/services/orchestration-layer/agent-v3
./scale-workers.sh status                # replici + backlog live
./scale-workers.sh set worker-claims 4   # scalare manuală
./scale-workers.sh auto --apply          # scalare pe metrici
```

## Loguri
```bash
docker logs -f didi-agent-v3
docker logs -f didi-framework
```

## Rebuild bază de date (alt host / reset)
Vezi rețeta completă în `services/data-layer/didiDatabase/REBUILD.md`.

---

# 7. Depanare

| Simptom | Cauză probabilă | Soluție |
|---|---|---|
| Baza DIDI e goală după build | seed absent înainte de primul boot | pune seed-ul + șterge volumul `didi-postgres-data` + re-rulează |
| Analize eșuează / fără rezultat LLM | chei API lipsă sau Lot 1 inaccesibil | verifică `agent-v3/.env` (chei + URL-uri Lot 1) |
| `401` pe orice cerere prin Kong | token JWT lipsă/invalid | obține token de la Keycloak; rutele publice (waitlist, verify-email) sunt exceptate |
| Redis fără chei framework | sync-redis neexecutat | rulează comanda de sync (§6) |
| Worker „mort" tăcut | reconectare broker | workerii se re-abonează automat; verifică `docker logs` |

---

*Documentul-pereche (operațional, cu inventar de scripturi): `backend/BUILD_AND_SCRIPTS.md`.*