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 5.1 or later - For development scripts
  • Docker Desktop - For containerized development environment
  • .NET SDK 9.0 - For backend development
  • Node.js 22.14+ - For frontend development
  • Git - For version control

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 follow this sequence: 1. Select 1 (🐳 Docker Operations) 2. Select 1 (Start services with watch mode)

This will start all services with hot reload enabled.

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:

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#

Create a .env file for custom configuration:

# CommandCenter Environment Variables
DOCKER_COMPOSE_DEV=true
NET_VERSION=9.0
DOMAIN_ZONE_NAME=localhost
BUILD_CONFIGURATION=Debug

Use the development menu to edit: Main Menu → 6 → 2

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#

# Start individual .NET service with watch
# Development Menu → 2 → 1 (Run .NET ServerAgent with watch)

# Or manually:
dotnet watch --project .\backend\CommandCenter.ServerAgent

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.