Skip to main content

​
Prerequisites

Before setting up the project locally, ensure you have the following installed:

​
Required

  • .NET SDK (LTS) - Download from dotnet.microsoft.com
    • Minimum version: .NET 6.0 or later
    • Verify installation: dotnet --version
  • SQL Server LocalDB - Included with Visual Studio or install via SQL Server Express
    • Verify installation: sqllocaldb info
  • Git - For cloning the repository

​
Optional

  • Redis - Required only if switching from in-memory cache to distributed cache
    • Windows: Use Redis on Windows or Docker
    • macOS/Linux: Install via package manager or Docker
  • Visual Studio 2022 or Visual Studio Code - Recommended IDEs with C# support

​
Initial setup

​
1. Clone the repository

git clone <repository-url>
cd chargeworx

​
2. Restore dependencies

dotnet restore
This downloads all NuGet packages required by the solution.

​
3. Build the solution

dotnet build
Verify the build completes without errors before proceeding.

​
4. Initialize the database

The application uses Entity Framework Core migrations. On first run, the database will be created automatically. To manually apply migrations: 
dotnet ef database update --project Chargeworx.Api

​
5. Seed initial data

The application includes data seeders that run on startup. See seeding and initializers for details on what data is created.

​
Running the applications

​
Start the API

dotnet run --project Chargeworx.Api
The API will be available at https://localhost:5001 (or the port specified in launchSettings.json).

​
Start the Admin UI

dotnet run --project Chargeworx.Admin
The Admin UI will be available at https://localhost:5003 (or the port specified in launchSettings.json).

​
Running both simultaneously

Open two terminal windows and run each project in a separate window, or use Visual Studio’s multiple startup projects feature.

​
Configuration

​
Database connections

Default ConnectionStrings in appsettings.Development.json target LocalDB databases:
  • API database: (localdb)\\mssqllocaldb with database name ChargeworxApi
  • Reporting database: (localdb)\\mssqllocaldb with database name ChargeworxReporting
To use a shared SQL Server instance instead:
  1. Update connection strings in appsettings.Development.json
  2. Ensure the SQL Server instance is accessible
  3. Run migrations to create the database schema

​
Cache configuration

By default, the application uses in-memory caching. To switch to Redis:
  1. Set Cache:UseInMemoryCache to false in appsettings.Development.json
  2. Provide Redis connection details: 
    "Cache": {
  "UseInMemoryCache": false,
  "Redis": {
    "Url": "localhost",
    "Port": 6379
  }
}
  3. Ensure Redis is running locally
See the switch cache backend runbook for more details.

​
Common setup issues

​
LocalDB not found

Error: A network-related or instance-specific error occurred while establishing a connection to SQL Server Solutions:
  • Verify LocalDB is installed: sqllocaldb info
  • Start LocalDB instance: sqllocaldb start mssqllocaldb
  • If missing, install SQL Server Express with LocalDB feature

​
Port already in use

Error: Failed to bind to address https://localhost:5001: address already in use Solutions:
  • Change the port in Properties/launchSettings.json
  • Kill the process using the port: netstat -ano | findstr :5001 (Windows) or lsof -i :5001 (macOS/Linux)
  • Use a different launch profile

​
Build errors after pulling latest changes

Error: Various compilation errors or missing dependencies Solutions:
  • Clean and rebuild: dotnet clean && dotnet restore && dotnet build
  • Delete bin and obj folders manually
  • Ensure you’re using the correct .NET SDK version

​
Database migration errors

Error: The database cannot be created because it already exists or migration conflicts Solutions:
  • Drop and recreate the database: dotnet ef database drop --project Chargeworx.Api
  • Apply migrations: dotnet ef database update --project Chargeworx.Api
  • Check for pending migrations: dotnet ef migrations list --project Chargeworx.Api

​
Redis connection failures

Error: It was not possible to connect to the redis server(s) Solutions:
  • Verify Redis is running: redis-cli ping (should return PONG)
  • Check Redis connection settings in appsettings.Development.json
  • Switch back to in-memory cache by setting Cache:UseInMemoryCache to true

​
SSL certificate errors

Error: The SSL connection could not be established or certificate trust issues Solutions:
  • Trust the development certificate: dotnet dev-certs https --trust
  • Clear and regenerate certificates: dotnet dev-certs https --clean && dotnet dev-certs https --trust

​
Troubleshooting tips

​
Enable detailed logging

Set the logging level to Debug in appsettings.Development.json: 
"Logging": {
  "LogLevel": {
    "Default": "Debug"
  }
}

​
Check application health

Once running, verify the API health endpoint: 
curl https://localhost:5001/Health

​
Verify database connectivity

Check that the database was created: 
sqllocaldb info mssqllocaldb

​
Review startup logs

Check console output for errors during application startup. Common issues include:
  • Missing configuration values
  • Database connection failures
  • Port binding conflicts

​
Next steps