Quick Start Guide#

Get the CommandCenter solution up and running for development in minutes.

Prerequisites#

Before you begin, ensure you have the following installed:

Required Software#

PowerShell 7+ - For development scripts (pwsh, not Windows PowerShell)
Docker Desktop - For containerized development environment
.NET SDK 10.0 - For backend development (pinned in global.json)
Node.js 22.14+ - For frontend development
pnpm 12 - Install it with pnpm's own installer, not corepack (which cannot run pnpm 12): iwr https://get.pnpm.io/install.ps1 -useb | iex on Windows, curl -fsSL https://get.pnpm.io/install.sh | sh - elsewhere. Then run corepack disable pnpm, so the corepack shim in the Node.js folder does not shadow it. In the repository pnpm switches itself to the version in the root package.json.
Git - For version control

Two things the stack needs are not in this repo and cannot be set up from here:

Traefik on the proxy docker network. Every service route is a Traefik label, so without it nothing is reachable by hostname. It lives in the reverse-proxy repo; see docs/docker-configuration.md.
SQL Server. There is no database service in either compose file — the stack expects a standalone container reachable as host.docker.internal.

The setup script checks for both and tells you if either is missing.

Verification Commands#

# Check PowerShell version
$PSVersionTable.PSVersion

# Verify Docker
docker --version
docker compose version

# Check .NET SDK
dotnet --version

# Verify Node.js and pnpm
node --version
pnpm --version

# Check Git
git --version

Quick Setup#

1. Clone the Repository#

git clone https://gitlab.tasperhosting.com/Tasper/CommandCenter.git
cd CommandCenter

2. Start Development Environment#

Use the enhanced development menu for the easiest setup:

.\run-dev-enhanced.ps1

Then: 1. Select 1 (🐳 Docker Operations) 2. Select 1 (Start services with watch mode)

That is the whole setup. Before starting anything, the menu runs scripts/dev-bootstrap.ps1, which prepares whatever the machine is missing:

What	How
`.env`	created from `.env.template`; values you already set are never touched
Keycloak dev credentials	generated once, written to `.env`, printed, and saved to `dev-credentials.local.md`
Keycloak realm	rendered from its template into an ignored folder
`proxy` network, `pnpm-store` volume	created — compose declares both external, so `up` will not make them
mTLS dev certificates	generated, with the thumbprint written to `.env` for you

It is idempotent: on a prepared machine it does nothing and says so. Run it directly at any time with .\scripts\dev-bootstrap.ps1, or from Utilities → 6. To rotate the generated credentials, Utilities → 7.

No file needs editing by hand.

3. Verify Installation#

Check that services are running:

# From the development menu:
# Main Menu → 4 (📊 Monitoring & Health) → 1 (Service health check)

# Or manually:
docker compose ps

4. Access the Application#

Once services are running:

The application: http://localhost:3070

3070 is the only host-mapped port, and it is the BFF. Everything else — the SPA, the APIs — is reached through it, which is the point of the gateway: the browser never talks to a downstream service directly. The Aspire dashboard is the one exception, on http://localhost:18888.

Development Workflow#

Daily Development#

Start the development menu:
```
.\run-dev-enhanced.ps1
```
Common workflows: - Start services: Main Menu → 1 → 1 - View logs: Main Menu → 1 → 2 - Run tests: Main Menu → 2 → 3 - Format code: Main Menu → 2 → 4

Code Changes#

The development environment supports hot reload:

Backend changes - Automatically recompiled and reloaded
Frontend changes - Automatically rebuilt and refreshed
Database changes - Apply migrations via Main Menu → 3 → 1

Testing#

Run different test suites:

# Via development menu: Main Menu → 2 → 3
# Then select:
# 1: Unit tests only
# 2: Integration tests only
# 3: All tests

Configuration#

Environment Variables#

.env is created for you on first run, from .env.template. You do not need to write one.

Edit it when you want to override something — Main Menu → 6 → 2 opens it. The bootstrap only ever adds keys that are missing, so anything you change there survives.

The one value worth knowing about is DOMAIN_ZONE_NAME. It has no default anywhere and every Traefik route and the Keycloak issuer are built from it, so a wrong value produces a stack that starts but cannot be reached by hostname.

Developing against Azure#

Instead of the emulators and the local SQL Server, the stack can run against your own Azure resources (App Configuration, Key Vault, storage, Azure SQL, Service Bus). An admin onboards you once; then Main Menu → 7 connects this machine and switches the target. The local stack stays the fallback when you are offline. See Developing against Azure.

Database Configuration#

Set up connection string in user secrets:

{
  "ConnectionStrings": {
    "DefaultConnection": "Server=host.docker.internal;Database=CommandCenter;User Id=docker;Password=docker"
  }
}

Apply database migrations: - Development Menu → 3 → 1

SSL Certificate#

For HTTPS development, install the root CA certificate: - Development Menu → 6 → 1

Troubleshooting#

Common Issues#

Docker Services Won't Start#

# Check Docker is running
docker info

# Clean up previous containers
# Development Menu → 1 → 7 → 4 (Full cleanup)

# Rebuild services
# Development Menu → 1 → 5

Database Connection Issues#

# Test database connection
# Development Menu → 3 → 3

# Reset database if needed
# Development Menu → 3 → 2

Build Failures#

# Clean artifacts
# Development Menu → 6 → 3

# Rebuild everything
# Development Menu → 5 → 1

Frontend Docker Build: `ERR_PNPM_LOCKFILE_CONFIG_MISMATCH`#

The frontend Dockerfile uses pnpm install --frozen-lockfile, which fails when pnpm-lock.yaml doesn't match ClientApps/command-center/package.json. This usually means a dependency was added on the host but the lockfile wasn't committed (or vice versa).

Fix:

cd ClientApps/command-center
pnpm install      # converges lockfile to match package.json
cd ..\..
docker compose -f compose.yaml -f compose.dev.yaml build commandcenter-frontend

Commit the updated pnpm-lock.yaml along with the package.json change.

Frontend Docker Build: `ERR_PNPM_META_FETCH_FAIL` / Network Errors#

If pnpm install inside the docker build fails with DNS or connection errors (EAI_AGAIN, ECONNRESET, ETIMEDOUT), the build is hitting the npm registry from the container and the network is flaky. The repo's .npmrc already configures generous retries (network-timeout=300000, fetch-retries=5), so this should be rare.

If it happens:

Check Docker Desktop networking (DNS, VPN/proxy interference)
Re-run the build — BuildKit's pnpm-store cache mount means already-downloaded packages aren't refetched
If repeated: the lockfile may have new entries not yet in the cache; consider running pnpm install on the host first to warm the global pnpm store, then docker build picks them up via the cache mount

Port Conflicts#

Check for conflicting processes:

# Check what's using ports 3000, 5000, 5001
netstat -ano | findstr ":3000 :5000 :5001"

# Stop conflicting processes or change ports in compose.dev.yaml

Getting Help#

Script documentation:
```
Get-Help .\run-dev-enhanced.ps1 -Full
```
Solution statistics: - Development Menu → 6 → 4
Service health: - Development Menu → 4 → 1
Error logs: - Development Menu → 4 → 3

Next Steps#

Development#

Read the Development Tools documentation for detailed menu usage
Review Docker Configuration for containerization details
Check Architecture for system design understanding

Frontend Development#

# Start Storybook for component development
cd ClientApps/command-center
pnpm run storybook

Backend Development#

# Out-of-Docker development is unsupported (see AGENTS.md): use the compose watch flow.
# A single project still builds on the host:
dotnet build .\backend\CommandCenter.WebApi -c Release

Database Development#

Migrations: Development Menu → 3 → 1
Schema changes: Use Entity Framework migrations
Data seeding: Implement in migration files or startup

Testing#

Unit tests: Focus on business logic and individual components
Integration tests: Test service interactions and API endpoints
End-to-end tests: Test complete user workflows

Production Deployment#

For production deployment information: - Review Deployment documentation - Check IIS Hosting for Windows deployment - See CI/CD pipeline configuration in .gitlab-ci.yml

Alternative Methods#

Manual Commands#

If you prefer command-line usage without the menu:

# Start services
docker compose --env-file .env -f compose.yaml -f compose.dev.yaml watch

# Build solution
pnpm exec cc build

# Run tests
dotnet test

# Format code
dotnet format

Legacy Development Script#

The original script is still available:

.\run-dev.ps1

However, the enhanced version is recommended for better organization and additional features.

Quick Start Guide#

Prerequisites#

Required Software#

Verification Commands#

Quick Setup#

1. Clone the Repository#

2. Start Development Environment#

3. Verify Installation#

4. Access the Application#

Development Workflow#

Daily Development#

Code Changes#

Testing#

Configuration#

Environment Variables#

Developing against Azure#

Database Configuration#

SSL Certificate#

Troubleshooting#

Common Issues#

Docker Services Won't Start#

Database Connection Issues#

Build Failures#

Frontend Docker Build: ERR_PNPM_LOCKFILE_CONFIG_MISMATCH#

Frontend Docker Build: ERR_PNPM_META_FETCH_FAIL / Network Errors#

Port Conflicts#

Getting Help#

Next Steps#

Development#

Frontend Development#

Backend Development#

Database Development#

Testing#

Production Deployment#

Alternative Methods#

Manual Commands#

Legacy Development Script#

Frontend Docker Build: `ERR_PNPM_LOCKFILE_CONFIG_MISMATCH`#

Frontend Docker Build: `ERR_PNPM_META_FETCH_FAIL` / Network Errors#