managing-apps/src/Managing.Api/README-ORLEANS-CONFIGURATION.md

Orleans Configuration

This document explains how to configure Orleans usage in the Managing API.

Overview

The Managing API now always runs Orleans for infrastructure, but supports configurable grain execution through the RunOrleansGrains configuration option. This allows you to control whether Orleans grains (bots, timers, reminders) are active during runtime.

Configuration Options

1. Configuration File (appsettings.json)

Add the Orleans grain control parameter to your appsettings file:

{
  "RunOrleansGrains": true
}

• RunOrleansGrains: Boolean value that controls whether Orleans grains (bots, timers, reminders) are active
  • true (default): Grains are active and can run timers/reminders
  • false: Grains are inactive, no timers or reminders will execute

Note: Orleans infrastructure is always enabled and configured. This flag only controls grain execution.

2. Environment Variables

You can also control Orleans grain execution through environment variables:

# Enable Orleans grains (bots, timers, reminders)
export RUN_ORLEANS_GRAINS=true

# Disable Orleans grains (infrastructure still runs)
export RUN_ORLEANS_GRAINS=false

Note: Environment variables take precedence over configuration file settings.

Configuration Files

The following configuration files have been updated with Orleans grain control settings:

• appsettings.json - Base configuration (RunOrleansGrains: true)
• appsettings.Development.json - Development configuration (RunOrleansGrains: false)
• appsettings.Oda.json - Oda environment (RunOrleansGrains: true)
• appsettings.Oda-docker.json - Oda Docker environment (RunOrleansGrains: true)
• appsettings.Sandbox.json - Sandbox environment (RunOrleansGrains: true)
• appsettings.SandboxLocal.json - Local Sandbox environment (RunOrleansGrains: true)
• appsettings.Production.json - Production environment (RunOrleansGrains: true)

Use Cases

Development Environment

• Set RunOrleansGrains: false to run Orleans infrastructure without active grains
• Useful for development and testing without bot execution overhead

Testing Environment

• Set RunOrleansGrains: false to test Orleans infrastructure without running bots
• Useful for integration testing without triggering actual trading operations

Production Environment

• Set RunOrleansGrains: true to enable full Orleans grain functionality
• Required for production trading bot operations

Docker/Container Environment

• Use environment variables for easy configuration
• Example: docker run -e RUN_ORLEANS_GRAINS=false ...

Implementation Details

The Orleans configuration is implemented in:

1. ApiBootstrap.cs - Orleans configuration logic
2. Program.cs - Application startup Orleans configuration

Security Considerations

• Orleans configuration is not sensitive and can be included in configuration files
• Environment variables provide runtime flexibility without code changes
• Default behavior maintains backward compatibility (Orleans enabled by default)

Troubleshooting

Orleans Not Starting

1. Orleans infrastructure is always enabled
2. Ensure PostgreSQL connection string for Orleans is configured
3. Check application logs for connection errors

Grains Not Running

1. Check RunOrleansGrains configuration value
2. Verify environment variable RUN_ORLEANS_GRAINS is not set to false
3. Ensure Orleans infrastructure is running properly

Configuration Not Applied

1. Verify configuration file syntax
2. Check environment variable spelling (RUN_ORLEANS_GRAINS)
3. Restart the application after configuration changes

Migration

Existing deployments will continue to work as Orleans grains are enabled by default. To control Orleans grain behavior:

Disable Grains (Keep Orleans Infrastructure)

1. Add "RunOrleansGrains": false to your appsettings file, or
2. Set environment variable RUN_ORLEANS_GRAINS=false

Development/Testing Setup

{
  "RunOrleansGrains": false
}

Note: Orleans infrastructure is always enabled and cannot be disabled.