Voltimax Platform

Appearance

Getting Started with Development ​

This guide will help you set up a local development environment for the Voltimax IoT Platform.

Prerequisites ​

Before you begin, ensure you have the following installed:

Required ​

  • Visual Studio 2022 (17.12+) or JetBrains Rider - for full IDE support
  • Visual Studio Code with C# Dev Kit extension - for lightweight development
  • Azure CLI - Install the Azure CLI (see Microsoft documentation) (for Azure deployments)
  • Node.js (v20+) - Download (for client SDK generation)

Clone the Repository ​

bash
git clone https://github.com/Voltimax/Voltimax.Iot.Platform.git
cd Voltimax.Iot.Platform

Build the Solution ​

bash
# Restore NuGet packages
dotnet restore

# Build the solution
dotnet build

# Run tests (optional)
dotnet test

Run with .NET Aspire ​

The easiest way to run the platform locally is using .NET Aspire, which orchestrates all services and dependencies:

bash
# Run the Aspire AppHost
dotnet run --project src/Voltimax.Iot.AppHost

Configure Keycloak ​

Aspire starts a Keycloak container automatically. Before the platform's migration service can bootstrap the application realm, you need to configure the master realm manually - this is a one-time setup.

Find the Keycloak URL in the Aspire dashboard, then open the Admin Console and sign in with the default credentials (admin / admin).

WARNING

Make sure you are working in the master realm for all steps below. The realm switcher is in the top-left corner of the Admin Console.

1. Import the admin-api client ​

The migration service authenticates to Keycloak using the admin-api client credentials. Import it into the master realm:

  1. Go to Clients → Import client
  2. Upload admin-api-client.json (or find it at docs/public/keycloak/admin-api-client.json in the repository)
  3. Click Save

2. Grant admin permissions to the service account ​

The admin-api service account needs the built-in admin realm role so it can create and configure realms:

  1. Go to Clients → admin-api → Service account roles tab
  2. Click Assign role, filter by Filter by realm roles
  3. Select the admin role and click Assign

3. Create the voltimax realm ​

The migration service will populate the realm, but the realm itself must exist first:

  1. Click the realm switcher (top-left) → Create realm
  2. Set Realm name to voltimax
  3. Leave Enabled on and click Create

INFO

Once these steps are complete, restart the platform (or let Aspire trigger the migration service). It will connect using the admin-api client and apply all realm configuration automatically.

Get Help ​

  • Review the configuration documentation (see docs)
  • Open an issue in the repository
  • Consult the Aspire Documentation (Microsoft docs)