orka.startup package

OrKa Startup Package

This package provides modular startup and service management for OrKa. It handles infrastructure services (Redis, Kafka), backend server management, and orchestrates the complete service lifecycle.

Key Components:

• Configuration management and path discovery

• Redis infrastructure (native & Docker)

• Kafka infrastructure (Docker-based)

• Backend server management

• Health monitoring and service readiness

• Cleanup and shutdown coordination

• Main orchestration logic

This package maintains backward compatibility with the original orka_start.py while providing a cleaner, more modular architecture.

async orka.startup.main() → None

Main entry point for starting and managing OrKa services.

This asynchronous function: 1. Determines which backend to use (Redis, Kafka, or dual) 2. Starts the appropriate infrastructure services (Redis natively, Kafka via Docker) 3. Waits for services to be ready 4. Launches the OrKa backend server 5. Monitors the backend process to ensure it’s running 6. Handles graceful shutdown on keyboard interrupt

The function runs until interrupted (e.g., via Ctrl+C), at which point it cleans up all started processes and containers.

orka.startup.run_startup() → None

Run the startup process with proper error handling.

This function serves as the main entry point and handles keyboard interrupts and unexpected errors gracefully.

orka.startup.start_infrastructure(backend: str) → Dict[str, Popen]

Start the infrastructure services natively.

Redis will be started as a native process on port 6380. Kafka services will still use Docker when needed.

Parameters:

backend – The backend type (‘redis’, ‘redisstack’, ‘kafka’, or ‘dual’)

Returns:

Dictionary of started processes

Return type:

Dict[str, subprocess.Popen]

Raises:

• RuntimeError – If Redis Stack is not available or fails to start

• subprocess.CalledProcessError – If Kafka Docker services fail to start

orka.startup.cleanup_services(backend: str, processes: Dict[str, Popen] = None) → None

Clean up and stop services for the specified backend.

Parameters:

• backend – The backend type (‘redis’, ‘redisstack’, ‘kafka’, or ‘dual’)

• processes – Dictionary of running processes to terminate

orka.startup.get_memory_backend() → str

Get the configured memory backend, defaulting to RedisStack.

orka.startup.get_docker_dir() → str

Get the path to the docker directory containing Docker Compose configuration.

This function attempts to locate the docker directory in both development and production environments by checking multiple possible locations.

Returns:

Absolute path to the docker directory

Return type:

str

Raises:

FileNotFoundError – If the docker directory cannot be found in any of the expected locations

orka.startup.start_backend(backend: str) → Popen

Start the OrKa backend server as a separate process.

This function launches the OrKa server module in a subprocess, allowing it to run independently while still being monitored by this parent process.

Parameters:

backend – The backend type (‘redis’, ‘kafka’, or ‘dual’)

Returns:

The process object representing the running backend

Return type:

subprocess.Popen

Raises:

Exception – If the backend fails to start for any reason

orka.startup.is_backend_running(backend_proc: Popen) → bool

Check if the backend process is still running.

Parameters:

backend_proc – The backend process to check

Returns:

True if the process is running, False otherwise

Return type:

bool

orka.startup.terminate_backend_process(backend_proc: Popen) → None

Gracefully terminate the backend process.

Parameters:

backend_proc – The backend process to terminate

orka.startup.start_native_redis(port: int = 6380) → Popen | None

Start Redis Stack natively on the specified port, with Docker fallback.

Parameters:

port – Port to start Redis on (default: 6380)

Returns:

The Redis process, or None if using Docker

Return type:

subprocess.Popen

Raises:

RuntimeError – If both native and Docker Redis fail to start

orka.startup.start_redis_docker(port: int = 6380) → None

Start Redis Stack using Docker as a fallback.

Parameters:

port – Port to start Redis on

Returns:

Docker process is managed by Docker daemon

Return type:

None

Raises:

RuntimeError – If Docker Redis fails to start

orka.startup.wait_for_redis(port: int, max_attempts: int = 30) → None

Wait for Redis to be ready and responsive (works for both native and Docker).

Parameters:

• port – Redis port to check

• max_attempts – Maximum number of connection attempts

Raises:

RuntimeError – If Redis doesn’t become ready within the timeout

orka.startup.start_kafka_docker() → None

Start Kafka services using Docker Compose.

Raises:

• subprocess.CalledProcessError – If Docker Compose commands fail

• FileNotFoundError – If docker directory cannot be found

orka.startup.wait_for_kafka_services() → None

Wait for Kafka services to be ready and responsive.

Raises:

RuntimeError – If Kafka services fail to become ready

orka.startup.initialize_schema_registry() → None

Initialize schema registry by creating a temporary KafkaMemoryLogger. This ensures schemas are registered at startup time.

orka.startup.wait_for_services(backend: str) → None

Wait for infrastructure services to be ready.

Parameters:

backend – The backend type (‘redis’, ‘redisstack’, ‘kafka’, or ‘dual’)

orka.startup.configure_backend_environment(backend: str) → dict

Configure environment variables for backend process.

Parameters:

backend – The backend type (‘redis’, ‘kafka’, or ‘dual’)

Returns:

Environment variables dictionary

Return type:

dict

orka.startup.get_service_endpoints(backend: str) → dict

Get service endpoint configuration for the specified backend.

Parameters:

backend – The backend type (‘redis’, ‘redisstack’, ‘kafka’, or ‘dual’)

Returns:

Dictionary containing service endpoint information

Return type:

dict

orka.startup.cleanup_specific_backend(backend: str) → None

Clean up services specific to a backend type.

Parameters:

backend – The backend type (‘redis’, ‘redisstack’, ‘kafka’, or ‘dual’)

orka.startup.terminate_all_processes(processes: Dict[str, Popen]) → None

Terminate all managed processes gracefully.

Parameters:

processes – Dictionary of process names to process objects

orka.startup.force_kill_processes(processes: Dict[str, Popen]) → None

Force kill all managed processes.

Parameters:

processes – Dictionary of process names to process objects

async orka.startup.monitor_backend_process(backend_proc: Popen) → None

Monitor the backend process and detect if it stops unexpectedly.

Parameters:

backend_proc – The backend process to monitor

Raises:

RuntimeError – If the backend process stops unexpectedly

orka.startup.check_process_health(processes: Dict[str, Popen]) → bool

Check the health of all managed processes.

Parameters:

processes – Dictionary of process name to process object

Returns:

True if all processes are healthy, False otherwise

Return type:

bool

orka.startup.display_service_endpoints(backend: str) → None

Display service endpoints for the configured backend.

Parameters:

backend – The backend type (‘redis’, ‘redisstack’, ‘kafka’, or ‘dual’)

orka.startup.display_startup_success() → None

Display successful startup message.

orka.startup.display_shutdown_message() → None

Display graceful shutdown message.

orka.startup.display_shutdown_complete() → None

Display shutdown complete message.

orka.startup.display_error(error: Exception) → None

Display error message during startup.

Parameters:

error – The exception that occurred

orka.startup.terminate_redis_process(redis_proc: Popen) → None

Gracefully terminate a Redis process.

Parameters:

redis_proc – The Redis process to terminate

orka.startup.cleanup_redis_docker() → None

Clean up Redis Docker services.

orka.startup.cleanup_kafka_docker() → None

Clean up Kafka Docker services.

orka.startup.get_kafka_services() → List[str]

Get the list of Kafka service names.

Returns:

List of Kafka service names

Return type:

List[str]

Subpackages

• orka.startup.infrastructure package
  • Infrastructure Management Package
  • check_process_health()
  • display_error()
  • display_service_endpoints()
  • display_shutdown_complete()
  • display_shutdown_message()
  • display_startup_success()
  • monitor_backend_process()
  • wait_for_services()
  • cleanup_kafka_docker()
  • get_kafka_services()
  • initialize_schema_registry()
  • start_kafka_docker()
  • wait_for_kafka_services()
  • cleanup_redis_docker()
  • start_native_redis()
  • start_redis_docker()
  • terminate_redis_process()
  • wait_for_redis()
  • Submodules
    • orka.startup.infrastructure.health module
      • Health Checking
      • wait_for_services()
      • monitor_backend_process()
      • display_service_endpoints()
      • display_startup_success()
      • display_shutdown_message()
      • display_shutdown_complete()
      • display_error()
      • check_process_health()
    • orka.startup.infrastructure.kafka module
      • Kafka Infrastructure Management
      • start_kafka_docker()
      • wait_for_kafka_services()
      • initialize_schema_registry()
      • cleanup_kafka_docker()
      • get_kafka_services()
    • orka.startup.infrastructure.redis module
      • Redis Infrastructure Management
      • start_native_redis()
      • start_redis_docker()
      • wait_for_redis()
      • cleanup_redis_docker()
      • terminate_redis_process()

Submodules

• orka.startup.backend module
  • Backend Server Management
  • start_backend()
  • terminate_backend_process()
  • is_backend_running()
• orka.startup.cleanup module
  • Service Cleanup
  • cleanup_services()
  • terminate_all_processes()
  • force_kill_processes()
  • cleanup_specific_backend()
• orka.startup.config module
  • Startup Configuration
  • get_docker_dir()
  • get_memory_backend()
  • get_service_endpoints()
  • configure_backend_environment()
• orka.startup.orchestrator module
  • Service Orchestrator
  • start_infrastructure()
  • main()
  • run_startup()