# Build from Source This guide provides instructions for building the VMS Adapter Plugin (VAP) from source code. Whether you are customizing the application or deploying a modified version, this guide walks you through the complete build process. ## Overview The VAP application consists of the following components built from source: - **Backend**: FastAPI Python service (`plugin/`) that manages VMS shims, analytics app shims, camera sync, event processing, and result routing. - **UI**: React 19 / Vite frontend (`ui/`) served by nginx, providing the provider dashboard. The `Dockerfile` in the repository root builds the backend image. The UI is built inside a multi-stage Docker build. Both are orchestrated by Docker Compose. ## Step 1: Clone the Repository Clone the repository and navigate to the VAP directory: ```bash git clone --filter=blob:none --sparse --branch release-2026.3.0 https://github.com/open-edge-platform/metro-ai-suite.git cd metro-ai-suite git sparse-checkout set vms-adapter-plugin cd vms-adapter-plugin ``` ## Step 2: Configure the Environment Copy the example environment file and edit it for your setup: ```bash cp .env.example .env ``` Set at minimum the following variables before building: | **Variable** | **Description** | |-----------------------------------------------|-------------------------------------------------------------------------| | `LVC_BASE_URL` | URL of the running LVC backend, e.g. `http://:4173` | | `MEDIAMTX_URL` | URL of the MediaMTX WebRTC server, e.g. `http://:8889` | | `NX_HOST` / `NX_USERNAME` / `NX_PASSWORD` | Nx Witness host and credentials (only if using Nx Witness) | | `NX_TLS_VERIFY` / `NX_CA_BUNDLE` | Nx TLS verification toggle and optional CA bundle path (default: `false`) | | `DLS_VISION_TLS_VERIFY` / `DLS_VISION_CA_BUNDLE` | DL Streamer TLS verification toggle and optional CA bundle path (default: `false`) | | `MQTT_TLS_ENABLED` / `MQTT_CA_BUNDLE` / `MQTT_CLIENT_CERT` / `MQTT_CLIENT_KEY` | MQTT TLS, CA bundle, and optional mutual TLS client certificate for the `dls_vision` subscriber | | `MQTT_BROKER_TLS_ENABLED` / `MQTT_BROKER_CA_BUNDLE` / `MQTT_BROKER_CLIENT_CERT` / `MQTT_BROKER_CLIENT_KEY` | MQTT TLS, CA bundle, and optional mutual TLS client certificate for the LVC broker subscriber | | `PG_PASSWORD` | PostgreSQL password (change from default) | Refer to `.env.example` for all available variables. Only the variables of the VMS and apps selected in Step 3 are used. For certificate path examples and TLS behavior details, see [TLS and Certificate Configuration](../how-to-guides/tls-and-certificates.md). ## Step 3: Generate the Configuration Generate `config/config.yaml` for the VMS and analytics apps you use. Both `--vms` and `--apps` are required; for example, Nx Witness with Loitering Detection and Live Video Captioning: ```bash ./setup.sh --vms nx --apps ld,lvc ``` Run `./setup.sh --list` for the available VMS and apps. See [Configure VAP](../get-started.md#configure-vap) for details. ## Step 4: Build and Start with Docker Compose Build all images and start the full stack: ```bash docker compose up -d --build ``` ### Customize the Build You can control the image registry and tag by setting environment variables before running the build command: ```bash export DOCKER_REGISTRY= # e.g. "docker.io/username/" export APP_VERSION= # e.g. "1.0.0" or "latest" ``` > [!NOTE] > If `DOCKER_REGISTRY` or `APP_VERSION` are not set, the defaults in the Docker Compose file > are used. ## Step 5: Verify the Build Check that all services are running: ```bash docker compose ps ``` Expected output — all services should show **healthy** or **running**: ```text NAME STATUS vms-adapter-backend Up (healthy) vms-adapter-ui Up (healthy) vms-adapter-postgres Up (healthy) ``` Verify the backend is up: ```bash curl -k https://localhost:3443/v1/health ``` ## Local Development ### Backend To run the backend outside Docker for local development: ```bash pip install -e ".[dev]" ./setup.sh --vms nx --apps ld,lvc export VMS_PLUGIN_CONFIG_PATH=$PWD/config/config.yaml uvicorn plugin.core.main:app --reload --port 8085 ``` Run tests: ```bash pytest tests/ -v ``` ### Frontend To run the React UI locally with hot reload: ```bash cd ui npm install npm run dev # http://localhost:5173 — proxies /v1 to backend npm run build ``` ## What to Do Next - [Get Started](../get-started.md): Complete the initial setup and start an analytics session. - [System Requirements](./system-requirements.md): Review hardware and software requirements. - [API Reference](../api-reference.md): Explore the available REST API endpoints. - [Troubleshooting](../troubleshooting.md): Find solutions to common build and deployment issues.