Setup Guide

Configure your environment to use BlueprintAX

1. Add the NuGet Feed

Add BlueprintAX to your nuget.config file at the project or solution root:

<?xml version="1.0" encoding="utf-8"?>
<configuration>
  <packageSources>
    <add key="nuget.org" value="https://api.nuget.org/v3/index.json" />
    <add key="BlueprintAX" value="https://blueprintax.rithmxo.org/v3/index.json" />
  </packageSources>
</configuration>

No credentials required — NuGet package reads are public.

2. Install the Meta-Package

One package, all platform features. Rithm.Platform.All includes all 6 required compliance packages plus SSO auth, tenancy, observability, and ServiceAX registration.

dotnet add package Rithm.Platform.All --version 1.*
dotnet restore

What's included

• Rithm.Platform.Core

• Rithm.Platform.Tenancy

• Rithm.Platform.Observability

• Rithm.Platform.Hosting

• Rithm.Platform.Security.Authorization

• Rithm.Platform.ServiceDiscovery

• Rithm.Platform.Auth

• Rithm.Infrastructure.Valkey

• Rithm.Infrastructure.SignalR

• Rithm.Infrastructure.ServiceRouter

• Rithm.Infrastructure.BatchProcessing

• + JWT Bearer auth

3. Wire Up Program.cs

Two lines. AddRithmPlatform registers JWT auth, SSO auth controller, tenant context, and service policy enforcement. UseRithmPlatform adds the middleware.

using Rithm.Platform;

var builder = WebApplication.CreateBuilder(args);

// Platform services: JWT auth + SSO controller + tenancy + policy enforcement
builder.Services.AddRithmPlatform(builder.Configuration, enforceServicePolicies: true);

// ... your other services ...

var app = builder.Build();

app.UseForwardedHeaders(/* ... */);
app.UseCors();
app.UseAuthentication();
app.UseAuthorization();

// Platform middleware — AFTER UseAuthorization
app.UseRithmPlatform();

app.MapControllers();
app.MapHealthChecks("/health");
app.Run();

For apps with custom auth schemes (e.g. InfraAX)

// Skip JWT registration — use your own
builder.Services.AddRithmPlatformCore();

4. Converting an Existing App

Most conversions are deletions. Remove the hand-rolled code that the platform replaces:

Delete this code

• Custom AuthController with PKCE logic — replaced by RithmAuthController
• builder.Services.AddJwtBearer(...) config — handled by AddRithmPlatform
• AddAuthentication(JwtBearerDefaults.AuthenticationScheme) — included
• Custom tenant middleware / X-Tenant-Id header parsing — replaced by ITenantContext
• Hand-rolled ServiceAX registration HTTP calls — automatic
• Custom Serilog setup for PII redaction — included in Observability
• Hardcoded Rithm.CastleGate* packages — deprecated

Keep or add

• nuget.config at repo root with BlueprintAX feed
• .ad.json at repo root (required by AppDeployer for build/start commands)
• Health endpoint: app.MapHealthChecks("/health")
• Forwarded headers middleware (for nginx)
• CORS policy allowing ecosystem domains

5. Choose Your Pattern

Two standard patterns. Pick based on your frontend needs.

Pattern 1

Single Server

.NET minimal API + optional Vite SPA served from wwwroot/. One process, one port.

Scaffold new app

ad init my-app --template rithmxo-vite

.ad.json

{
  "name": "myapp",
  "framework": "dotnet",
  "buildCommand": "cd frontend && npm ci && npm run build && cd .. && cp -r frontend/dist src/MyApp.Api/wwwroot && dotnet publish src/MyApp.Api -c Release -o .",
  "startCommand": "./MyApp.Api"
}

Pattern 2

Dual Server

Next.js standalone frontend + .NET backend as separate processes. Nginx routes /api/* to backend, everything else to frontend.

Scaffold new app

ad init my-app --template rithmxo-nextjs

.ad.json

{
  "name": "myapp",
  "framework": "dotnet",
  "isDualServer": true,
  "buildCommand": "cd frontend && npm ci && npm run build && cd .. && dotnet publish backend/src/MyApp.Api -c Release -o .",
  "startCommand": "./MyApp.Api"
}

Next.js must use output: 'standalone' in next.config.js. The deployer auto-detects and runs node server.js.

6. Frontend SSO Integration

Don't hardcode SSO URLs. Let the backend handle redirection — it knows the correct UserAX per environment.

// On 401 or when user needs to log in:
function redirectToLogin() {
  const returnUrl = encodeURIComponent(window.location.href);
  window.location.href = `/api/auth/start?returnUrl=${returnUrl}`;
}

Don't do this

// ❌ Hardcoded SSO URL — wrong authority per environment
window.location.href = "https://sso.rithm.services/login";

// ❌ NEXT_PUBLIC_SSO_AUTHORITY is baked at build time, not runtime
window.location.href = process.env.NEXT_PUBLIC_SSO_AUTHORITY;

7. Verify Compliance

After conversion, check your app in the DeployerAX compliance scanner:

Open DeployerAX Admin → Compliance
Find your app — status should be Compliant
Platform badge should show Full (Platform.All)
SSO and ServiceAX should both show ✓

If any required packages show as missing, the compliance scanner will suggest fixes per file.

8. Push Packages (maintainers only)

Create an API key with packages:push scope, then:

dotnet pack -c Release
dotnet nuget push ./bin/Release/MyPackage.1.0.0.nupkg \
  --source https://blueprintax.rithmxo.org/v3/index.json \
  --api-key <your-api-key>