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

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.
infra-check: Validates that Postgres, Redis, RabbitMQ, and HAProxy are responsive.
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.
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.
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.

4.2 KiB Raw Blame History