Local Development

Overview

The HonseFarm.AppHost project is a .NET Aspire application orchestrator designed exclusively for local development environments. It serves as the development-time command center that automatically configures, launches, and manages the entire HonseFarm distributed application stack on your local machine. This project is not intended for production use and should never be deployed to production servers.

Running the HonseFarm.AppHost project out of the box will spin up 4 "HonseFarm" servers with their fileservers. In practice this will result in 15-20 applications running at the same time, to simulate a full federation.

What is .NET Aspire?

.NET Aspire is Microsoft's opinionated stack for building observable, production-ready distributed applications. At its core is the app model, a code-first, single source of truth that defines your application's services, resources, and dependencies. Aspire provides orchestration capabilities that enhance the local development experience by eliminating complex configuration files and automating service discovery, environment variables, and container management.

HonseFarm.AppHost Configuration

The AppHost's sole purpose is to make distributed application development feel like working on a single monolithic application, with all the benefits of microservices architecture but none of the local development complexity. The AppHost is configured through appsettings.json, which defines the entire development topology including multiple servers, file servers, and infrastructure dependencies.

AppHostConfiguration

{
  "StorageFolderRoot": "E:\\Honse",           // Root path for file storage (fileservers)
  "FileServersEnabled": true,                 // Enable/disable file server resources (for debugging)
  "FileServersCount": 2,                      // Default number of file server shards per server.
  "EnableCdn": false,                         // Enable CDN/Distribution layer (for debugging)
  "UseExternalMonitoringStack": false         // Use external monitoring instead of Aspire-managed (for debugging victioria stack)
}

ServerConfiguration

Defines multiple HonseFarm server instances that will be orchestrated:

BaseHttpPort & BaseHttpsPort: Starting port numbers (5000/5100) that increment for each server instance

Servers Array: Each server instance includes:

• ServerId: Unique identifier (e.g., "ALPHA", "CATSRUS", "Heart")
• Name: Display name for the server
• Description: Server description shown to users
• Role: Either "Server" (full server) or "Bootstrap" (federation discovery only)
• ServerType: "Public", "PrivateListed", or "PrivateUnlisted"
• ServerJoinSecret: Password for private servers
• FileServerCount: Number of file servers for this instance (determines architecture):
  • 1: AllInOne file server (uploads + downloads in one service)
  • 2-4: Main file server + Shard file servers
  • 5+: Main + Distribution node + Shards
• UseDnsBootstrap: Whether to use DNS-based federation discovery
• DnsBootstrapHostname: Federation bootstrap endpoint
• GroupUidPrefix: Prefix for syncshell UIDs (e.g., "MSS", "CA", "LUV")
• Fileservers: Array of file server configurations with storage limits and retention policies

Example Configuration

The default appsettings.json orchestrates four complete server environments:

1. btstrap1 (Bootstrap Server)

   • Role: Federation discovery
   • Purpose: Lightweight server that maintains the network of federated servers
   • File Servers: 1 (minimal storage)

2. ALPHA (Full Server)

   • Role: Public server
   • File Servers: 2 (Main + 1 Shard)
   • Storage: 20 GiB cache + cold storage enabled

3. CATSRUS (Private Listed Server)

   • Role: Password-protected but discoverable
   • ServerJoinSecret: "meowsers"
   • File Servers: 4 (Main + Distribution + 2 Shards)
   • GroupUidPrefix: "CA"

4. Heart (Private Unlisted Server)

   • Role: Invite-only server
   • File Servers: 6 (Main + Distribution + 4 Shards)
   • GroupUidPrefix: "LUV"

What Resources Does AppHost Orchestrate?

When you run the AppHost project, it automatically starts and manages:

Core Infrastructure

• PostgreSQL Database: Shared database for all server instances
• Redis Cache: Shared cache and message broker
• Monitoring Stack (if not using external):
  • VictoriaMetrics (metrics collection)
  • VictoriaLogs (log aggregation)
  • VictoriaTrace (distributed tracing)
  • Grafana (visualization dashboards)

Per-Server Resources

For each server defined in ServerConfiguration.Servers:

1. HonseFarm.Server Instance

   • Main server application
   • Configured with unique ServerId, ports, and federation settings
   • Connects to shared PostgreSQL and Redis

2. HonseFarm.AdminPanel Instance

   • Web-based administration interface
   • One per server instance

3. File Server Architecture (based on FileServerCount):

   FileServerCount = 1:

   • 1x AllInOne file server (handles both uploads and downloads)

   FileServerCount = 2-4:

   • 1x Main file server (accepts uploads, authoritative source)
   • N-1 Shard file servers (user-facing downloads)

   FileServerCount = 5+:

   • 1x Main file server (uploads)
   • 1x Distribution/CDN file server (caching layer)
   • N-2 Shard file servers (downloads)

Configuration File Generation

The AppHost uses ConfigFileGenerator and various builder classes to automatically generate:

• appsettings.Development.json for each server instance
• appsettings.Development.json for each file server instance
• appsettings.Development.json for each admin panel instance

These files are tailored to each resource's role and include:

• Unique ports (HTTP/HTTPS)
• Connection strings to shared infrastructure
• JWT secrets for inter-service communication
• Federation settings and bootstrap endpoints
• Storage paths and limits

Architecture Pattern

The AppHost follows a Builder Pattern architecture with specialized builders:

var builder = DistributedApplication.CreateBuilder(args);

// Orchestrator coordinates all builders
var orchestrator = serviceProvider.GetRequiredService<ResourceOrchestrator>();

// Builders for each resource type
- InfrastructureBuilder: PostgreSQL, Redis
- DatabaseBuilder: Database initialization
- RedisBuilder: Cache configuration
- ServerBuilder: HonseFarm.Server instances
- FileServerBuilder: File server instances
- AdminPanelBuilder: Admin panel instances
- MonitoringBuilder: Metrics/logs/traces stack

Each builder:

1. Reads configuration templates
2. Generates resource-specific configurations
3. Adds resources to the Aspire app model with proper dependencies
4. Configures service discovery and networking

Service Discovery & Dependencies

Aspire automatically handles service discovery between resources:

// Example dependency chain
builder.AddProject<HonseFarm.Server>("alpha-server")
    .WithReference(postgres)    // Server depends on database
    .WaitFor(postgres);          // Wait for DB to be ready

builder.AddProject<HonseFarm.Fileserver>("alpha-main-fileserver")
    .WithReference(server)       // FileServer needs server reference
    .WithReference(redis)        // FileServer uses Redis
    .WaitFor(server)
    .WaitFor(redis);

Resources reference each other by name (e.g., "alpha-server", "cache"), and Aspire automatically:

• Injects correct connection strings
• Configures network routing
• Manages startup ordering based on dependencies
• Provides health monitoring

Development Workflow

Running the AppHost

1. Set HonseFarm.AppHost as the startup project in Visual Studio
2. Press F5 or run dotnet run from the AppHost directory
3. Aspire Dashboard opens showing all orchestrated resources
4. All services start concurrently while respecting dependency order

What You Get

• Aspire Dashboard:

  • Real-time resource status
  • Logs from all services
  • Distributed traces
  • Metrics visualization
  • Easy access to all service endpoints

• Multiple Complete Environments:

  • 4 independent HonseFarm servers
  • Each with its own file server architecture
  • Each with its own admin panel
  • All sharing infrastructure (DB, Redis, Monitoring)

• Automatic Configuration:

  • No manual appsettings.json editing
  • No manual port management
  • No manual connection string configuration
  • Service discovery "just works"

Hot Reload & Debugging

Since Aspire orchestrates .NET projects directly:

• Hot Reload works for code changes
• Debugging works across all services
• Breakpoints work in any orchestrated project
• Console output visible in Aspire Dashboard

Key Differences: AppHost vs. Installer

Templates and Defaults

The AppHost relies on configuration templates defined in appsettings.json:

• FederationTemplate: Default federation settings for servers
• HonseFarmTemplate: Default server behavior and limits
• MainFileServerTemplate: Default Main file server configuration
• DistributionFileServerTemplate: Default CDN/Distribution node settings
• ShardFileServerTemplate: Default Shard file server configuration
• AllInOneFileServerTemplate: Default all-in-one file server settings

These templates ensure consistency across all orchestrated instances while allowing per-instance customization through the ServerConfiguration.Servers array.