Local Development

Step-by-step guide for running the full Ampra stack locally for development and testing.

---

Prerequisites

Tool	Version	Purpose
Docker Desktop	24.0+	Container runtime for all dependencies
.NET SDK	10.0	Backend API development
Node.js	20+	Frontend UI development
npm	10+	Package management

---

Quick Start

The run.bat script at the repository root automates the entire local setup:

.\run.bat

This script performs three steps:

Step 1 — Lint Checks

Both backend and frontend are linted before starting:

[1/2] Backend (dotnet format) — verifies C# code style
[2/2] Frontend (eslint)       — verifies TypeScript/React rules

If either check fails, startup is aborted. Fix lint errors before retrying.

Step 2 — Start Backend Dependencies

Seven Docker containers are started in sequence:

Order	Container	Image	Ports	Volume
1	ampra-db	postgres:16-alpine	5432:5432	ampra-db-data
2	ampra-minio	quay.io/minio/minio	9000:9000, 9001:9001	ampra-minio-data
3	ampra-mongo	mongo:8.0	27017:27017	ampra-mongo-data
4	ampra-redis	redis:7-alpine	6379:6379	ampra-redis-data
5	ampra-emqx	emqx/emqx:5.8	1883:1883, 18083:18083	ampra-emqx-data
6	ampra-ml	ampra-ml:latest	5050:5050	—
7	ampra-ingestion	ampra-ingestion:latest	—	—

After containers start, the ASP.NET Core API runs via dotnet run at http://localhost:5001.

Step 3 — Start UI

The React UI starts in a separate terminal via Vite dev server at http://localhost:5002.

---

Default Credentials (Local Dev Only)

Service	Username	Password
PostgreSQL	ampra	ampra123
MongoDB	ampra	ampra123
MinIO	ampra	ampra123
Redis	—	No auth
EMQX	admin	changeme

---

Local Service Endpoints

Service	URL	Notes
API	http://localhost:5001	ASP.NET Core
UI	http://localhost:5002	Vite dev server (HMR enabled)
PostgreSQL	localhost:5432	Database: ampradb
MongoDB	localhost:27017	Database: ampradb
MinIO Console	http://localhost:9001	Web management UI
MinIO API	http://localhost:9000	S3-compatible API
EMQX Dashboard	http://localhost:18083	MQTT broker management
EMQX MQTT	localhost:1883	MQTT protocol
Redis	localhost:6379	Cache / job store
ML Service	http://localhost:5050	Python Flask API

---

Configuration Files

API (src/Ampra.Web/appsettings.json)

Pre-configured for local development with default credentials. Key sections:

{
  "ConnectionStrings": {
    "DefaultConnection": "Host=localhost;Port=5432;Database=ampradb;...",
    "MongoDb": "mongodb://ampra:ampra123@localhost:27017/ampradb?authSource=admin",
    "Redis": "localhost:6379"
  },
  "MinIO": {
    "Endpoint": "localhost:9000",
    "UseSSL": false
  },
  "ML": {
    "ServiceUrl": "http://localhost:5050"
  },
  "MqttBroker": {
    "Host": "localhost",
    "Port": 1883
  }
}

MQTT Ingestion (src/Ampra.MQTT/appsettings.json)

{
  "Mqtt": {
    "BrokerHost": "localhost",
    "BrokerPort": 1883,
    "ClientId": "ampra-ingestion-worker",
    "TopicFilter": "ampra/sources/+/data"
  },
  "Ingestion": {
    "ThrottleSeconds": 10,
    "DeduplicationWindowSeconds": 30,
    "MaxPayloadBytes": 65536
  }
}

EMQX Broker (src/Ampra.MQTT/emqx.conf)

Configured for local development with HTTP authentication callbacks pointing to host.docker.internal:5001. The broker delegates all auth/ACL decisions to the API.

Vite (src/Ampra.UI/vite.config.ts)

Dev server on port 5002 with path alias @ → src/, TanStack Router plugin, and Tailwind CSS v4.

---

Running Individual Components

Backend Only

cd src/Ampra.Web
dotnet run

Requires Docker containers for PostgreSQL, MongoDB, Redis, MinIO to be running.

Frontend Only

cd src/Ampra.UI
npm run dev

Requires the API to be running at http://localhost:5001.

ML Service Only

cd src/Ampra.ML
docker build -t ampra-ml:latest .
docker run -p 5050:5050 \
  -e MONGO_URL=mongodb://ampra:ampra123@host.docker.internal:27017/ampradb?authSource=admin \
  -e REDIS_URL=redis://host.docker.internal:6379/0 \
  -e MINIO_ENDPOINT=host.docker.internal:9000 \
  -e MINIO_ACCESS_KEY=ampra \
  -e MINIO_SECRET_KEY=ampra123 \
  ampra-ml:latest

---

Database Migrations

Entity Framework Core manages PostgreSQL schema migrations. Migrations are automatically applied on API startup.

# Create a new migration
cd src/Ampra.Web
dotnet ef migrations add MigrationName --project ../Ampra.Infrastructure

# Apply migrations manually
dotnet ef database update --project ../Ampra.Infrastructure