veza/docs/archive/root-md/report.md

📊 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:

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).

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.