Skip to content

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
  • 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:

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#

  1. Start the development menu: 

    .\run-dev-enhanced.ps1

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

Database Configuration#

  1. Set up connection string in user secrets: 

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

  2. 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:

  1. Check Docker Desktop networking (DNS, VPN/proxy interference)
  2. Re-run the build — BuildKit's pnpm-store cache mount means already-downloaded packages aren't refetched
  3. 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#

  1. Script documentation: 

    Get-Help .\run-dev-enhanced.ps1 -Full

  2. Solution statistics: - Development Menu → 6 → 4

  3. Service health: - Development Menu → 4 → 1

  4. Error logs: - Development Menu → 4 → 3

Next Steps#

Development#

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.