95 lines
4.2 KiB
Markdown
95 lines
4.2 KiB
Markdown
|
# 📊 Veza Lab Environment Report
|
||
|
|
|
||
|
|
## Overview
|
||
|
|
We have successfully established a robust **Veza Lab Environment** orchestrated via a single command. This environment replicates the full production stack, including infrastructure, backend services, and a unified ingress gateway, all running locally for development and testing.
|
||
|
|
|
||
|
|
**Command to Start:**
|
||
|
|
```bash
|
||
|
|
make dev-lab
|
||
|
|
```
|
||
|
|
|
||
|
|
## 🏗️ Architecture
|
||
|
|
|
||
|
|
The Lab environment differs slightly from production to facilitate easy debugging (running apps on host) while keeping infrastructure isolated (in Docker).
|
||
|
|
|
||
|
|
```mermaid
|
||
|
|
graph TD
|
||
|
|
User[User / Browser] -->|http://localhost:80| HAProxy(Docker: veza-lab-haproxy)
|
||
|
|
|
||
|
|
subgraph "Docker Infrastructure (veza-lab-net)"
|
||
|
|
Postgres[(Postgres 16)]
|
||
|
|
Redis[(Redis 7)]
|
||
|
|
RabbitMQ[(RabbitMQ 3)]
|
||
|
|
HAProxy
|
||
|
|
end
|
||
|
|
|
||
|
|
subgraph "Host Machine (Mac/Linux)"
|
||
|
|
HAProxy -->|Proxy| Backend[veza-backend-api :8080]
|
||
|
|
HAProxy -->|Proxy| Chat[veza-chat-server :8081]
|
||
|
|
HAProxy -->|Proxy| Stream[veza-stream-server :8082]
|
||
|
|
HAProxy -->|Proxy| Web[apps/web :3000]
|
||
|
|
|
||
|
|
Backend --> Postgres
|
||
|
|
Chat --> Postgres
|
||
|
|
Stream --> Postgres
|
||
|
|
|
||
|
|
Backend --> Redis
|
||
|
|
Chat --> Redis
|
||
|
|
Stream --> Redis
|
||
|
|
|
||
|
|
Chat --> RabbitMQ
|
||
|
|
end
|
||
|
|
```
|
||
|
|
|
||
|
|
### Components
|
||
|
|
|
||
|
|
| Service | Port (Host) | DB Connection | Status |
|
||
|
|
|---------|-------------|---------------|--------|
|
||
|
|
| **HAProxy** | `:80` | N/A | ✅ Proxying to Host |
|
||
|
|
| **Backend API** | `:8080` | `veza_lab` | ✅ Healthy |
|
||
|
|
| **Chat Server** | `:8081` | `veza_chat` | ✅ Healthy |
|
||
|
|
| **Stream Server** | `:8082` | `veza_lab` | ✅ Healthy |
|
||
|
|
| **Frontend** | `:3000` | N/A | ✅ Fixed (QueryClient added) |
|
||
|
|
| **Postgres** | `:5432` | N/A | ✅ v16 |
|
||
|
|
| **Redis** | `:6379` | N/A | ✅ v7 |
|
||
|
|
| **RabbitMQ** | `:5672` | N/A | ✅ v3 + Mgmt |
|
||
|
|
|
||
|
|
## 🛠️ Implementation Details
|
||
|
|
|
||
|
|
### 1. Unified Orchestration (`make dev-lab`)
|
||
|
|
The `make dev-lab` command chains the following steps:
|
||
|
|
1. **`infra-up`**: Starts Docker containers defined in `infra/docker-compose.lab.yml`.
|
||
|
|
* *Improvement*: Added **HAProxy** to this stack.
|
||
|
|
* *Feature*: Auto-creates databases (`veza_lab`, `veza_chat`, `veza_stream`) and installs required extensions (`uuid-ossp`, `pgcrypto`, `btree_gin`) on startup.
|
||
|
|
2. **`infra-check`**: Validates that Postgres, Redis, RabbitMQ, and HAProxy are responsive.
|
||
|
|
3. **`migrate-all`**: Runs migrations for all services.
|
||
|
|
* *Resolution*: Solved conflict between Chat and Stream migrations (both using `001_initial`) by isolating Chat to its own `veza_chat` database. Stream shares `veza_lab` with Backend to access core `tracks`.
|
||
|
|
4. **`services-up`**: Launches Go, Rust, and Node.js applications in the background.
|
||
|
|
* *Fix*: Corrected log paths and removed cleanup traps so services persist after the script finishes.
|
||
|
|
5. **`health-all`**: Polls health endpoints (`/health`, `/readyz`) to confirm startup.
|
||
|
|
|
||
|
|
### 2. HAProxy Integration
|
||
|
|
We added HAProxy to serve as the single entry point, mimicking production routing locally.
|
||
|
|
* **Config**: `docker/haproxy/haproxy.lab.cfg`
|
||
|
|
* **Routing**:
|
||
|
|
* `/api` -> Backend API
|
||
|
|
* `/ws/chat` -> Chat Server
|
||
|
|
* `/hls`, `/stream` -> Stream Server
|
||
|
|
* `*` -> Frontend (React App)
|
||
|
|
* **Network Magic**: configured with `extra_hosts: host.docker.internal:host-gateway` to allow the Dockerized HAProxy to route traffic to apps running natively on your host machine.
|
||
|
|
|
||
|
|
### 3. Frontend Fixes
|
||
|
|
During verification, the frontend crashed with a `QueryClientProvider` error.
|
||
|
|
* **Fix**: Modified `apps/web/src/main.tsx` to wrap the application in `<QueryClientProvider>`, ensuring React Query functions correctly.
|
||
|
|
|
||
|
|
## ✅ Verification Status
|
||
|
|
|
||
|
|
* **Infrastructure**: All containers up.
|
||
|
|
* **Migrations**: All applied successfully (idempotent).
|
||
|
|
* **Services**: All processes running and reachable.
|
||
|
|
* **Frontend**: Loads via `http://localhost`.
|
||
|
|
|
||
|
|
## ⏭️ Next Steps
|
||
|
|
* **Development**: You can now edit code in `apps/web` or any backend service; the changes will reflect (for web/Go via live reload if configured, or restart for Rust).
|
||
|
|
* **Shutdown**: Currently, services run in background. Use `pkill -f veza` or kill ports to stop host apps. `docker compose -f infra/docker-compose.lab.yml down` stops infra.
|