Skip to content

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 ​

bash
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.

ServicePort(s)Management URLCredentials
SQL Server 20221433SSMS / Azure Data Studiosa / see .env
RabbitMQ5672 (AMQP), 15672 (mgmt)http://localhost:15672guest / guest
Redis6379—no auth (dev)
Seq Logging1234 (UI), 5341 (ingest)http://localhost:1234no auth (dev)
OpenTelemetry Collector4317 (gRPC), 4318 (HTTP)——

Memory allocation recommendation ​

Machine RAMDocker Desktop memoryServices you can run
16 GB6 GBInfrastructure + 2–3 backend services
32 GB14 GBInfrastructure + all backend services
64 GB28 GBFull stack (backend + all frontend apps)

Starting and Stopping Services ​

bash
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 ​

bash
# [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 ​

bash
# [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 ​

FieldValue
Serverlocalhost,1433
AuthenticationSQL Server Authentication
Loginsa
PasswordSee dev/.env (ask team lead if missing)

Create dev databases ​

sql
-- 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 ​

bash
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 ​

bash
# 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.

bash
# 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 ​

BackendPortProtocol
Seq (traces)5341OTLP over HTTP
Local Prometheus (optional)9090Prometheus 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:

json
{
  "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:

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:

bash
# 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 ​

SymptomCauseFix
SQL Server not startingPort 1433 already in useStop MSSQL local instance: sudo systemctl stop mssql-server
RabbitMQ UI shows "Connection refused"Container not healthy yetWait 30 s after docker-compose up
ECONNREFUSED in backend logsService started before DockerEnsure docker-compose up -d ran first
Seq shows no logsBackend not configured for SeqCheck appsettings.Development.json Seq URL
ng serve exits immediatelyNx cache corruptionRun npx nx reset then retry
Redis connection timeoutRedis container crasheddocker-compose restart redis

Internal Documentation — Microtec