Skip to content

Property Management System - Setup & Troubleshooting Guide

This comprehensive guide will help you set up your development environment for the Property Management System and resolve common issues.

Table of Contents

Prerequisites

System Requirements

Minimum Requirements: - OS: Windows 10/11, macOS 10.15+, or Ubuntu 18.04+ - RAM: 8GB (16GB recommended) - Storage: 20GB free space - CPU: 4 cores (8 cores recommended)

Required Software

.NET Development

# Download and install .NET 8 SDK
# Windows: https://dotnet.microsoft.com/download/dotnet/8.0
# macOS: brew install --cask dotnet
# Ubuntu: sudo apt-get install dotnet-sdk-8.0

# Verify installation
dotnet --version
# Expected output: 8.0.x

Node.js and npm

# Install Node.js 18+ and npm 9+
# Windows: Download from https://nodejs.org/
# macOS: brew install node
# Ubuntu: curl -fsSL https://deb.nodesource.com/setup_18.x | sudo -E bash - && sudo apt-get install -y nodejs

# Verify installation
node --version  # Should be 18.x or higher
npm --version   # Should be 9.x or higher

Docker Desktop

# Download and install Docker Desktop
# Windows/macOS: https://www.docker.com/products/docker-desktop
# Ubuntu: Follow official Docker installation guide

# Verify installation
docker --version
docker-compose --version

# Start Docker Desktop and ensure it's running
docker run hello-world

Git Configuration

# Configure Git with your information
git config --global user.name "Your Name"
git config --global user.email "your.email@example.com"

# Optional: Set up SSH keys for GitHub
ssh-keygen -t ed25519 -C "your.email@example.com"
# Add the public key to your GitHub account

Quick Start

1. Clone and Setup

# Clone the repository
git clone https://github.com/property-management/property-management.git
cd property-management

# Restore .NET dependencies
dotnet restore

# Install frontend dependencies
cd frontend/web
npm ci
cd ../..

# Copy environment configuration
cp src/AppHost/appsettings.Development.example.json src/AppHost/appsettings.Development.json

2. Start the Application

# Start all services with .NET Aspire
dotnet run --project src/AppHost/PropertyManagement.AppHost

# The Aspire dashboard will open automatically at https://localhost:15888
# All service URLs will be displayed in the dashboard

3. Verify Setup

# Run tests to ensure everything works
dotnet test

# Run frontend tests
cd frontend/web
npm test
cd ../..

Detailed Setup

1. Repository Setup

Fork and Clone

# Fork the repository on GitHub first, then:
git clone https://github.com/YOUR_USERNAME/property-management.git
cd property-management

# Add upstream remote
git remote add upstream https://github.com/property-management/property-management.git

# Verify remotes
git remote -v

Branch Setup

# Create and switch to develop branch
git checkout -b develop origin/develop

# Create your feature branch
git checkout -b feature/your-feature-name

2. .NET Backend Setup

Restore Dependencies

# Restore all project dependencies
dotnet restore

# Verify all projects build successfully
dotnet build

Project Structure Verification

# Verify the solution structure
dotnet sln list

# Expected output should include:
# - src/AppHost/PropertyManagement.AppHost
# - src/Services/Identity/PropertyManagement.Identity.WebApi
# - src/Services/Property/PropertyManagement.Property.WebApi
# - And other microservices...

Install Development Tools

# Install useful .NET global tools
dotnet tool install -g dotnet-ef                    # Entity Framework CLI
dotnet tool install -g dotnet-aspnet-codegenerator  # Code generators
dotnet tool install -g dotnet-reportgenerator-globaltool  # Test coverage reports

# Verify tools installation
dotnet ef --version

3. Frontend Setup

Install Dependencies

cd frontend/web

# Install all npm dependencies
npm ci

# Verify installation
npm list --depth=0

Verify Frontend Configuration

# Check TypeScript configuration
npx tsc --noEmit

# Run linting
npm run lint

# Check if Tailwind CSS is working
npm run build

Environment Configuration

.NET Configuration

Development Settings

// src/AppHost/appsettings.Development.json
{
  "ConnectionStrings": {
    "DefaultConnection": "Host=localhost;Database=PropertyManagement;Username=postgres;Password=yourpassword",
    "Redis": "localhost:6379"
  },
  "IdentityServer": {
    "Authority": "https://localhost:5001",
    "ApiName": "property-management-api",
    "ApiSecret": "your-api-secret"
  },
  "Logging": {
    "LogLevel": {
      "Default": "Information",
      "Microsoft.AspNetCore": "Warning",
      "Microsoft.EntityFrameworkCore": "Information"
    }
  }
}

Environment Variables

# Windows (PowerShell)
$env:ASPNETCORE_ENVIRONMENT = "Development"
$env:ASPNETCORE_URLS = "https://localhost:5001;http://localhost:5000"

# macOS/Linux (Bash)
export ASPNETCORE_ENVIRONMENT=Development
export ASPNETCORE_URLS="https://localhost:5001;http://localhost:5000"

Frontend Configuration

Environment Variables

# frontend/web/.env.local
NEXT_PUBLIC_API_URL=https://localhost:5001
NEXT_PUBLIC_ENVIRONMENT=development
NEXTAUTH_URL=http://localhost:3000
NEXTAUTH_SECRET=your-nextauth-secret

TypeScript Configuration

// frontend/web/tsconfig.json (verify these settings)
{
  "compilerOptions": {
    "strict": true,
    "noImplicitAny": true,
    "strictNullChecks": true,
    "target": "ES2022",
    "module": "ESNext",
    "moduleResolution": "bundler"
  }
}

Database Setup

PostgreSQL with Docker

Quick Setup

# Start PostgreSQL container
docker run --name property-management-postgres \
  -e POSTGRES_DB=PropertyManagement \
  -e POSTGRES_USER=postgres \
  -e POSTGRES_PASSWORD=yourpassword \
  -p 5432:5432 \
  -d postgres:15

# Verify connection
docker exec -it property-management-postgres psql -U postgres -d PropertyManagement

Using Docker Compose

# docker-compose.dev.yml
version: '3.8'
services:
  postgres:
    image: postgres:15
    environment:
      POSTGRES_DB: PropertyManagement
      POSTGRES_USER: postgres
      POSTGRES_PASSWORD: yourpassword
    ports:
      - "5432:5432"
    volumes:
      - postgres_data:/var/lib/postgresql/data

  redis:
    image: redis:7-alpine
    ports:
      - "6379:6379"
    volumes:
      - redis_data:/data

volumes:
  postgres_data:
  redis_data:

# Start services
docker-compose -f docker-compose.dev.yml up -d

# Stop services
docker-compose -f docker-compose.dev.yml down

Database Migrations

Run Initial Migrations

# Navigate to each service and run migrations
cd src/Services/Identity/PropertyManagement.Identity.WebApi
dotnet ef database update

cd ../../../Property/PropertyManagement.Property.WebApi
dotnet ef database update

# Continue for other services...

Create New Migration

# Example: Adding a new migration to Property service
cd src/Services/Property/PropertyManagement.Property.Infrastructure
dotnet ef migrations add AddPropertyLocationFeature \
  --project PropertyManagement.Property.Infrastructure \
  --startup-project ../PropertyManagement.Property.WebApi \
  --output-dir Migrations

Redis Setup

Docker Setup

# Start Redis container
docker run --name property-management-redis \
  -p 6379:6379 \
  -d redis:7-alpine

# Test Redis connection
docker exec -it property-management-redis redis-cli ping
# Expected output: PONG

Frontend Setup

Next.js Development Server

Start Development Server

cd frontend/web

# Start with hot reload
npm run dev

# The application will be available at http://localhost:3000

Build and Production Mode

# Create production build
npm run build

# Start production server
npm run start

Package Management

Update Dependencies

# Check for outdated packages
npm outdated

# Update packages (be careful with major version updates)
npm update

# Install new package
npm install package-name

# Install development dependency
npm install --save-dev package-name

Troubleshooting

Common .NET Issues

Port Already in Use

# Error: "Address already in use"
# Solution: Find and kill process using the port

# Windows
netstat -ano | findstr :5001
taskkill /PID <PID> /F

# macOS/Linux
lsof -ti:5001 | xargs kill -9

# Or change the port in launchSettings.json

SSL Certificate Issues

# Error: "SSL certificate problem"
# Solution: Trust development certificates

dotnet dev-certs https --clean
dotnet dev-certs https --trust

# If still having issues, try:
dotnet dev-certs https --trust --verbose

Entity Framework Issues

# Error: "No migrations found"
# Solution: Ensure you're in the correct directory

# Check current migrations
dotnet ef migrations list

# If no migrations exist, create initial migration
dotnet ef migrations add InitialCreate

# Reset database (WARNING: This will delete all data)
dotnet ef database drop --force
dotnet ef database update

Common Frontend Issues

Node.js Version Mismatch

# Error: "Unsupported Node.js version"
# Solution: Use Node Version Manager

# Install nvm (if not already installed)
# macOS/Linux: curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash
# Windows: Download from https://github.com/coreybutler/nvm-windows

# Install and use correct Node.js version
nvm install 18
nvm use 18

# Verify version
node --version

Package Installation Issues

# Error: "Package not found" or dependency issues
# Solution: Clear cache and reinstall

# Clear npm cache
npm cache clean --force

# Delete node_modules and package-lock.json
rm -rf node_modules package-lock.json

# Reinstall packages
npm install

TypeScript Compilation Errors

# Error: TypeScript compilation errors
# Solution: Check and fix TypeScript configuration

# Check TypeScript version
npx tsc --version

# Compile and check for errors
npx tsc --noEmit

# If using strict mode, gradually fix type issues
# Consider temporarily disabling strict mode for development

Database Connection Issues

PostgreSQL Connection Failed

# Error: "Connection to database failed"
# Solutions:

# 1. Check if PostgreSQL is running
docker ps | grep postgres

# 2. Verify connection string
# Check appsettings.Development.json

# 3. Test connection manually
docker exec -it property-management-postgres psql -U postgres -l

# 4. Check firewall settings (Windows)
# Ensure ports 5432 and 6379 are open

# 5. Reset PostgreSQL container
docker stop property-management-postgres
docker rm property-management-postgres
# Then recreate the container

Migration Issues

# Error: "Migration failed"
# Solutions:

# 1. Check if database exists
dotnet ef database list

# 2. Drop and recreate database (WARNING: Data loss)
dotnet ef database drop
dotnet ef database update

# 3. Rollback to previous migration
dotnet ef database update PreviousMigrationName

# 4. Remove problematic migration
dotnet ef migrations remove

Aspire and Docker Issues

Aspire Dashboard Not Opening

# Error: Dashboard not accessible
# Solutions:

# 1. Check if the AppHost is running
dotnet run --project src/AppHost/PropertyManagement.AppHost --verbose

# 2. Verify dashboard URL in console output
# Look for: "Now listening on: https://localhost:xxxxx"

# 3. Check if antivirus is blocking the application
# Temporarily disable antivirus and try again

# 4. Clear browser cache or try incognito mode

Docker Container Issues

# Error: Docker containers not starting
# Solutions:

# 1. Check Docker Desktop status
docker info

# 2. Restart Docker Desktop
# GUI: Right-click Docker icon -> Restart
# Command: docker system prune (WARNING: Removes unused containers)

# 3. Check available disk space
docker system df

# 4. Update Docker Desktop to latest version

Network and Firewall Issues

Windows Firewall

# Allow .NET applications through Windows Firewall
New-NetFirewallRule -DisplayName "Property Management Dev" -Direction Inbound -Protocol TCP -LocalPort 5000,5001,3000 -Action Allow

macOS Firewall

# Check if firewall is blocking connections
sudo /usr/libexec/ApplicationFirewall/socketfilterfw --getglobalstate

# Add application to firewall exceptions if needed

Performance Issues

Slow Build Times

# Solutions for slow builds:

# 1. Exclude unnecessary files from build
# Add to .gitignore and ensure proper exclusions in project files

# 2. Use build optimization
dotnet build --configuration Release --verbosity minimal

# 3. Clear build cache
dotnet clean
dotnet restore --no-cache

# 4. Increase Docker memory allocation
# Docker Desktop -> Settings -> Resources -> Memory (8GB+)

High Memory Usage

# Monitor memory usage:

# 1. Check .NET process memory
dotnet-monitor collect --process-id <PID>

# 2. Monitor Docker containers
docker stats

# 3. Optimize garbage collection
# Add to appsettings.json:
{
  "System.GC.Server": true,
  "System.GC.Concurrent": true
}

Performance Optimization

Development Environment

Visual Studio / VS Code Settings

// .vscode/settings.json
{
  "dotnet.defaultSolution": "PropertyManagement.sln",
  "typescript.preferences.includePackageJsonAutoImports": "on",
  "editor.formatOnSave": true,
  "editor.codeActionsOnSave": {
    "source.fixAll.eslint": true
  },
  "files.exclude": {
    "**/node_modules": true,
    "**/bin": true,
    "**/obj": true
  }
}

Git Configuration for Performance

# Optimize Git for large repositories
git config core.preloadindex true
git config core.fscache true
git config gc.auto 256

# Use Git LFS for large files (if needed)
git lfs track "*.psd"
git lfs track "*.mp4"

Build Optimization

.NET Build Performance

<!-- Directory.Build.props (in repository root) -->
<Project>
  <PropertyGroup>
    <TreatWarningsAsErrors>false</TreatWarningsAsErrors>
    <WarningsAsErrors />
    <DebugType>portable</DebugType>
    <AccelerateBuildsInVisualStudio>true</AccelerateBuildsInVisualStudio>
  </PropertyGroup>
</Project>

Frontend Build Performance

// next.config.js optimizations
module.exports = {
  experimental: {
    turbo: {
      loaders: {
        '.svg': ['@svgr/webpack'],
      },
    },
  },
  webpack: (config, { dev, isServer }) => {
    if (dev && !isServer) {
      config.optimization.splitChunks = {
        chunks: 'all',
        cacheGroups: {
          vendor: {
            test: /[\\/]node_modules[\\/]/,
            name: 'vendors',
            chunks: 'all',
          },
        },
      };
    }
    return config;
  },
};

Development Tools

Visual Studio Code

  • C# Dev Kit: C# development support
  • REST Client: Test API endpoints
  • Thunder Client: Alternative API testing
  • GitLens: Enhanced Git capabilities
  • Prettier: Code formatting
  • ESLint: JavaScript/TypeScript linting
  • Tailwind CSS IntelliSense: CSS utility suggestions
  • Docker: Container management
  • PostgreSQL: Database management

Browser Extensions

  • React Developer Tools: Debug React components
  • Redux DevTools: State management debugging (if using Redux)
  • Lighthouse: Performance auditing

Useful Scripts

Development Scripts

# Create a development script file: scripts/dev.sh
#!/bin/bash

echo "Starting Property Management System..."

# Start Docker services
docker-compose -f docker-compose.dev.yml up -d

# Wait for services to be ready
sleep 10

# Start the application
dotnet run --project src/AppHost/PropertyManagement.AppHost

Testing Scripts

# Create a testing script: scripts/test.sh
#!/bin/bash

echo "Running all tests..."

# Run .NET tests
dotnet test --logger "console;verbosity=detailed"

# Run frontend tests
cd frontend/web
npm test -- --coverage --watchAll=false
cd ../..

echo "All tests completed!"

Getting Help

Documentation Resources

  • Project Documentation: /documentations folder
  • API Documentation: Available in Aspire dashboard
  • Architecture Documentation: /docs folder

Community and Support

  • GitHub Issues: Report bugs and request features
  • GitHub Discussions: Ask questions and share ideas
  • Team Communication: Use designated Slack channels

Debugging Resources

  • Application Insights: Monitor application performance
  • Aspire Dashboard: Real-time service monitoring
  • Browser DevTools: Frontend debugging
  • .NET Diagnostic Tools: Memory and performance profiling

Need additional help? Check the CONTRIBUTING.md file for development workflows and coding standards, or create an issue on GitHub with detailed information about your problem.