Skip to content

Welcome to CML Cloud Manager

A production-ready reference implementation for managing, monitoring, and operating CML Workers with real-time updates, background processing, and role-based access control.

This project demonstrates how to build a modern web application using the neuroglia-python framework. It provides a solid foundation for clean, scalable, and maintainable applications with Python while showcasing:

  • Multi SubApp FastAPI architecture (API + UI)
  • CQRS + domain events + background jobs (APScheduler)
  • Real-time UI updates via Server-Sent Events (SSE)
  • Automated worker & labs refresh cycles
  • Role-based access (Admin / Manager / User)
  • Observability with OpenTelemetry

Cml Cloud Manager demo

Online Documentation

Getting Started

New to the project? Start here:

  1. Install & Run: Follow the Installation Guide then Running the App.
  2. Login Roles: Use provided Keycloak test users (admin, manager, user).
  3. Explore Workers: View current workers; admins/managers can create, start/stop, terminate; all roles can view metrics.
  4. Real-Time Updates: Watch the status badge and worker list update automatically via SSE.
  5. Labs Data: Open a worker details modal and switch to the Labs tab to see lab records (auto-refreshed every 30 min + manual refresh).

Documentation Map

  • Architecture: Core patterns, CQRS, DI, background processing (overview)
  • Security: Authentication flows & RBAC (auth flows)
  • Real-Time Updates: SSE event stream & UI auto-refresh (see Architecture > Real-Time Updates)
  • Worker Monitoring: Metrics, labs refresh, thresholds (worker monitoring)
  • Development: Makefile, testing, docs, AI agent guide
  • Deployment: Docker & environment setup (docker environment)
graph TD
    subgraph "FastAPI Application"
        A["Controllers (API Layer)"] --> B["Mediator (Neuroglia)"];
        B --> C{"Handlers (Application Layer)"};
        C --> C1["Commands (Write)"];
        C --> C2["Queries (Read)"];
        C1 --> D["Repositories (Data Access)"];
        C2 --> D;
        D --> E["MongoDB (Persistence)"];
    end

🛠️ Technology Stack

Backend

Frontend

Infrastructure

👤 Roles Overview

Role Capabilities
User View workers, metrics, labs data (read-only)
Manager All User capabilities + start/stop workers, update tags
Admin Full lifecycle (create/import, start/stop, terminate), monitoring control

Real-time updates & labs visibility apply to all roles; action buttons are filtered by role.

🤝 Contributing

This is a starter app template. When adapting for your project:

Keep the Patterns

  • ✅ Authentication architecture
  • ✅ CQRS structure
  • ✅ Dependency injection setup
  • ✅ Frontend build pipeline
  • ✅ Docker development environment

Customize the Domain

  • 🔧 Replace Task entities with your models
  • 🔧 Update UI components and styling
  • 🔧 Configure Keycloak realms and roles
  • 🔧 Adapt database schema
  • 🔧 Add your API endpoints

Extend as Needed

  • ➕ Additional auth providers
  • ➕ More command/query handlers
  • ➕ Event sourcing
  • ➕ Background jobs
  • ➕ API versioning

📚 Additional Resources

Documentation

🔄 Real-Time & Background Processes

  • SSE Stream: /api/events/stream pushes worker lifecycle, metrics, labs updates.
  • Labs Refresh Job: Global recurrent job (labs-refresh-global) runs every 30 minutes plus once at startup.
  • Metrics Collection: Poll interval configurable (worker_metrics_poll_interval).
  • Status Badge: Workers view displays connection state: connected / reconnecting / disconnected / error.

🆘 Getting Help

  1. Check Common Issues
  2. Review relevant documentation section
  3. Search GitHub Issues
  4. Create a new issue with details

Ready to start? Head to the Docker Environment guide to get your development environment running!