Local Development Setup

Complete guide to running the full Microtec ERP dev stack on your local machine.

Audience: All developers
Prerequisites: Docker Desktop installed with at least 8 GB memory allocated

---

Quick Start

cd ~/Projects/microtec/Erp/dev
docker-compose up -d

That's it. All infrastructure services start in the background. See details below.

---

Infrastructure Services

All services are defined in dev/docker-compose.yml. They are started once and left running throughout your workday.

Service	Port(s)	Management URL	Credentials
SQL Server 2022	1433	SSMS / Azure Data Studio	sa / see .env
RabbitMQ	5672 (AMQP), 15672 (mgmt)	http://localhost:15672	guest / guest
Redis	6379	—	no auth (dev)
Seq Logging	1234 (UI), 5341 (ingest)	http://localhost:1234	no auth (dev)
OpenTelemetry Collector	4317 (gRPC), 4318 (HTTP)	—	—

Memory allocation recommendation

Machine RAM	Docker Desktop memory	Services you can run
16 GB	6 GB	Infrastructure + 2–3 backend services
32 GB	14 GB	Infrastructure + all backend services
64 GB	28 GB	Full stack (backend + all frontend apps)

---

Starting and Stopping Services

cd ~/Projects/microtec/Erp/dev

# Start all services in background
docker-compose up -d

# Start a specific service only
docker-compose up -d sql-server redis

# Stop all services (preserves data volumes)
docker-compose stop

# Stop and remove containers (data volumes preserved)
docker-compose down

# Stop and remove everything including volumes (data wiped!)
docker-compose down -v

# View running services
docker-compose ps

# Follow all service logs
docker-compose logs -f

# Follow a specific service log
docker-compose logs -f rabbitmq

---

IDE Launchers

Pre-configured scripts that open the correct run configurations in your IDE.

JetBrains Rider

# [ACTION] Start Rider with all backend run configurations pre-loaded
./dev/START-WITH-RIDER.sh

This script:

1. Starts Docker infrastructure services
2. Opens Rider with the Microtec.Platforms.sln solution
3. Loads all run configurations from .run/ directory

VS Code

# [ACTION] Start VS Code with all launch configurations
./dev/START-WITH-VSCODE.sh

This script:

1. Starts Docker infrastructure services
2. Opens VS Code with the multi-root workspace file
3. Pre-selects the compound launch configuration "Start All"

---

SQL Server Setup

Connect with a SQL client

Field	Value
Server	localhost,1433
Authentication	SQL Server Authentication
Login	sa
Password	See dev/.env (ask team lead if missing)

Create dev databases

-- Run in SSMS or Azure Data Studio
CREATE DATABASE [Microtec_AppsPortal_Dev];
CREATE DATABASE [Microtec_BusinessOwners_Dev];
CREATE DATABASE [Microtec_Infrastructure_Dev];

Apply EF Core migrations

cd Platforms

# Accounting module
dotnet ef database update \
  --project Src/AppsPortal/Accounting/AppsPortal.Infrastructure \
  --startup-project Src/AppsPortal/Accounting/AppsPortal.Apis

# BusinessOwners module
dotnet ef database update \
  --project Src/BusinessOwners/BusinessOwners.Infrastructure \
  --startup-project Src/BusinessOwners/BusinessOwners.Apis

---

RabbitMQ Setup

Access management UI

Open http://localhost:15672 in your browser.

• Username: guest
• Password: guest

Create default exchanges and queues

The application creates queues and exchanges automatically on startup via MassTransit topology. No manual setup required.

Common operations

# Purge all messages from a queue (dev only!)
curl -s -u guest:guest -X DELETE \
  http://localhost:15672/api/queues/%2F/erp-events/contents

# List all queues
curl -s -u guest:guest \
  http://localhost:15672/api/queues | jq '.[].name'

---

Redis Setup

Redis runs without authentication in the dev environment.

# Connect via CLI (if redis-cli is installed)
redis-cli -h localhost -p 6379

# Test connectivity
redis-cli ping
# Expected: PONG

# View all keys (dev only — never run in production!)
redis-cli keys "*"

# Flush all keys (dev reset)
redis-cli flushall

---

Seq Logging

Seq is a structured log viewer that aggregates logs from all running backend services.

Access

Open http://localhost:1234

No authentication required in dev.

Useful queries

# Show errors from the last 30 minutes
@Level = 'Error' and @Timestamp >= Now() - 30m

# Show logs from a specific service
SourceContext like '%AppsPortal%'

# Show logs for a specific tenant
TenantId = 'my-tenant-id'

# Show slow requests (> 1 second)
Elapsed > 1000

# Show all SQL queries
SourceContext = 'Microsoft.EntityFrameworkCore.Database.Command'

Configure a backend service to send logs to Seq

Microtec.Web.Hosting pre-configures Serilog to write to Seq. The default endpoint is http://localhost:5341. No additional configuration is needed.

---

OpenTelemetry

The OTel Collector receives traces and metrics from all backend services.

Backends supported in dev

Backend	Port	Protocol
Seq (traces)	5341	OTLP over HTTP
Local Prometheus (optional)	9090	Prometheus scrape

View traces

Traces from .NET services are automatically sent to Seq via the OTel → Seq exporter. In Seq, search for TraceId to correlate a distributed request across services.

---

Backend Service Configuration (appsettings.Development.json)

Each backend service reads from appsettings.json and appsettings.Development.json. The development overrides should point to your local Docker services:

{
  "ConnectionStrings": {
    "DefaultConnection": "Server=localhost,1433;Database=Microtec_AppsPortal_Dev;User Id=sa;Password=YOUR_SA_PASS;TrustServerCertificate=true;"
  },
  "Redis": {
    "Configuration": "localhost:6379"
  },
  "RabbitMq": {
    "Host": "localhost",
    "Port": 5672,
    "Username": "guest",
    "Password": "guest"
  },
  "Seq": {
    "ServerUrl": "http://localhost:5341"
  },
  "Keycloak": {
    "Authority": "http://localhost:8080/auth/realms/microtec",
    "ClientId": "apps-portal"
  }
}

[WARNING] Never commit appsettings.Development.json files that contain actual passwords. These files are .gitignored.

---

Frontend Proxy Configuration

The Angular dev server proxies API requests to avoid CORS issues. The proxy config is at MFE-Apps/proxy.conf.json:

{
  "/api": {
    "target": "http://localhost:5000",
    "secure": false,
    "changeOrigin": true
  }
}

This is applied automatically when you run npx nx serve. The Angular app sends API requests to localhost:PORT which are forwarded to the backend service.

---

Resetting Your Dev Environment

When things get into a bad state, use this reset sequence:

# 1. Stop all running backend processes (Ctrl+C in each terminal)

# 2. Reset Docker containers and volumes
cd ~/Projects/microtec/Erp/dev
docker-compose down -v

# 3. Restart Docker infrastructure
docker-compose up -d

# 4. Re-apply database migrations
cd ~/Projects/microtec/Erp/Platforms
dotnet ef database update \
  --project Src/AppsPortal/Accounting/AppsPortal.Infrastructure \
  --startup-project Src/AppsPortal/Accounting/AppsPortal.Apis

# 5. Clear frontend cache
cd ~/Projects/microtec/Erp/MFE-Apps
rm -rf node_modules .nx/cache dist
npm i --f

---

Troubleshooting

Symptom	Cause	Fix
SQL Server not starting	Port 1433 already in use	Stop MSSQL local instance: sudo systemctl stop mssql-server
RabbitMQ UI shows "Connection refused"	Container not healthy yet	Wait 30 s after docker-compose up
ECONNREFUSED in backend logs	Service started before Docker	Ensure docker-compose up -d ran first
Seq shows no logs	Backend not configured for Seq	Check appsettings.Development.json Seq URL
ng serve exits immediately	Nx cache corruption	Run npx nx reset then retry
Redis connection timeout	Redis container crashed	docker-compose restart redis

---

Related Documentation

• New Developer Day 1 Checklist
• Backend Onboarding
• Frontend Onboarding