BMS/README.md

BMS — Data Centre Infrastructure Management

A full-stack DCIM platform with live sensor dashboards, alarm management, power/cooling monitoring, and simulated sensor bots.

Stack: Next.js 16 · FastAPI · PostgreSQL + TimescaleDB · MQTT (Mosquitto) · Docker Compose

---

Table of Contents

1. Prerequisites
2. Quick Start — Docker Compose
3. Environment Variables
4. Verify Everything Is Running
5. Accessing the App
6. Ports Reference
7. Local Development (without Docker)
8. Project Structure
9. Stopping & Resetting

---

Prerequisites

Requirement	Minimum version	Check
Docker	24+	docker --version
Docker Compose	v2 (bundled with Docker Desktop / Engine)	docker compose version
Git	any	git --version

That's it for the Docker path — Node and Python are not needed on the host.

---

Quick Start — Docker Compose

1. Clone the repo

git clone https://git.rdx4.com/youruser/bms.git
cd bms

2. Create the environment files

Copy the example files and fill in your values:

cp backend/.env.example backend/.env
cp frontend/.env.local.example frontend/.env.local

Open each file and follow the inline comments. At minimum you need to set the Clerk keys (see Environment Variables below).

3. Start all services

docker compose up --build

The first run downloads base images and builds the containers — this takes a few minutes. On subsequent starts it is much faster:

docker compose up

4. Done

Open your browser at http://your-server:5646

---

Environment Variables

backend/.env

# Database — matches the db service in docker-compose.yml, no change needed
DATABASE_URL=postgresql+asyncpg://dcim:dcim_pass@db:5432/dcim

# MQTT broker — matches the mqtt service, no change needed
MQTT_HOST=mqtt
MQTT_PORT=1883

# Clerk authentication
# Get these from https://dashboard.clerk.com → Your App → API Keys
CLERK_SECRET_KEY=sk_test_REPLACE_ME
CLERK_JWKS_URL=https://YOUR_APP.clerk.accounts.dev/.well-known/jwks.json

# CORS — add your frontend origin if you expose the backend directly
# Leave empty when using the built-in Next.js proxy (recommended)
CORS_ORIGINS=[]

DEBUG=true

frontend/.env.local

# Clerk authentication (same app as above)
NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY=pk_test_REPLACE_ME
CLERK_SECRET_KEY=sk_test_REPLACE_ME

# Clerk redirect paths — no need to change these
NEXT_PUBLIC_CLERK_SIGN_IN_URL=/sign-in
NEXT_PUBLIC_CLERK_SIGN_UP_URL=/sign-up
NEXT_PUBLIC_CLERK_AFTER_SIGN_IN_URL=/dashboard
NEXT_PUBLIC_CLERK_AFTER_SIGN_UP_URL=/dashboard

# API path — leave as-is, Next.js proxies /api/backend/* to the backend internally
NEXT_PUBLIC_API_URL=/api/backend

Where do I get Clerk keys? Sign up free at https://clerk.com → create an application → go to API Keys. Copy the Publishable key and Secret key into both files above.

---

Verify Everything Is Running

docker compose ps

All five services should show healthy or running:

NAME                STATUS
dcim_mqtt           running (healthy)
dcim_db             running (healthy)
dcim_backend        running (healthy)
dcim_simulators     running
dcim_frontend       running

Check individual logs if something looks wrong:

docker compose logs backend     # FastAPI logs
docker compose logs frontend    # Next.js logs
docker compose logs db          # PostgreSQL logs
docker compose logs simulators  # Sensor bot logs

Test the backend API directly:

curl http://localhost:8000/api/health
# Expected: {"status":"ok"}

---

Accessing the App

What	URL
Dashboard	http://your-server:5646
API docs (Swagger)	http://your-server:5646/api/backend/docs
API docs (ReDoc)	http://your-server:5646/api/backend/redoc

Reverse proxy tip: The frontend is the only service that needs to be publicly reachable. Point Nginx / Caddy / Traefik at port 5646. The backend, database, and MQTT broker communicate only on the internal Docker network.

Browser → Reverse Proxy → :5646 (Next.js)
                               ↓ server-side rewrite
                           :8000 (FastAPI) — internal only

---

Ports Reference

Service	Host port	Container port	Notes
Frontend (Next.js)	5646	5646	Public-facing
Backend (FastAPI)	8000	8000	Internal; exposed for dev/debugging
Database (PostgreSQL)	5433	5432	Mapped to 5433 to avoid conflicts with any local Postgres
MQTT (Mosquitto)	1883	1883	Internal

---

Local Development (without Docker)

Useful if you want hot-reload on the frontend or backend without rebuilding containers.

Database only via Docker

docker compose up db mqtt

Backend

Requires Python 3.12+.

cd backend
python -m venv .venv
source .venv/bin/activate        # Windows: .venv\Scripts\activate
pip install -r requirements.txt
uvicorn main:app --reload --port 8000

Frontend

Requires Node 22+ and pnpm.

# Install pnpm if you don't have it
npm install -g pnpm

cd frontend
pnpm install
pnpm dev

Frontend dev server runs on http://localhost:3000 by default.

Simulators

cd simulators
pip install -r requirements.txt
python main.py

---

Project Structure

bms/
├── frontend/            Next.js 16 app (TypeScript, Tailwind, shadcn/ui, Recharts)
│   ├── app/             Pages (dashboard, cooling, power, alarms, floor-map, …)
│   ├── components/      Shared UI components
│   └── lib/             API client, contexts, utilities
│
├── backend/             FastAPI app
│   ├── api/routes/      REST endpoints (alarms, cooling, power, env, …)
│   ├── core/            DB connection, config
│   ├── models/          SQLAlchemy models
│   └── services/        MQTT subscriber, alarm engine, WebSocket manager
│
├── simulators/          Python sensor bots — publish fake DCIM telemetry over MQTT
│   └── bots/            Per-device bots: CRAC, UPS, generator, PDU, env, …
│
├── infra/
│   └── mosquitto/       Mosquitto broker config
│
└── docker-compose.yml   Orchestrates all services

---

Stopping & Resetting

# Stop all containers (data is preserved)
docker compose down

# Stop and delete the database volume (full reset — all data lost)
docker compose down -v

# Rebuild images after code changes
docker compose up --build