CMBCluster

Multi-tenant Streamlit Platform for Research

CMBCluster is a multi-tenant Streamlit platform designed specifically for research teams. Built on the proven JupyterHub architecture pattern, it provides isolated, persistent research environments for each user while maintaining enterprise-grade security and scalability.

Architecture

The platform follows the JupyterHub architecture pattern with these key components:

graph TB
    Users[👥 Users] --> Proxy[🌐 Proxy]
    Proxy --> Hub[🎯 Hub - Authenticate user]
    
    Hub --> PV[💾 Pods + Volumes / USER SESSION]
    
    CloudVolumes[☁️ Cloud Volumes] --> PV
    ImageRegistry[📦 Image Registry] --> PV
    
    Proxy -.->|ROUTE INFOSEND| Hub
    Hub -.->|SIGNED OUTUSER REDIRECT| Proxy
    Proxy -.->|SIGNED IN USERREDIRECT| PV
    Hub -.->|VOLUME PROVIDE/POD CREATE/USER REDIRECT| PV
    Hub -.->|CULL PODSIF STALE| PV
    
    subgraph "Kubernetes Cluster"
        Proxy
        Hub
        PV
    end
    
    style Users fill:#f9f,stroke:#333,stroke-width:2px
    style Proxy fill:#9f9,stroke:#333,stroke-width:2px
    style Hub fill:#9f9,stroke:#333,stroke-width:2px
    style PV fill:#99f,stroke:#333,stroke-width:2px
    style CloudVolumes fill:#bbf,stroke:#333,stroke-width:2px
    style ImageRegistry fill:#bbf,stroke:#333,stroke-width:2px

Features

🔐 Enterprise Security

Google OAuth Integration: Seamless single sign-on
RBAC: Role-based access control with admin/user permissions
Network Policies: Kubernetes-native network isolation
Pod Security: Non-root containers with security contexts

🚀 Scalable Infrastructure

Auto-scaling: Horizontal pod autoscaling based on demand
Resource Management: Configurable CPU/memory limits per user
Load Balancing: NGINX ingress with SSL termination
High Availability: Multi-replica deployments with health checks

🔬 Research-Focused

Scientific Computing: Pre-installed research libraries (pandas, numpy, scipy, matplotlib)
Interactive Analysis: Streamlit-based data exploration interface
Persistent Workspaces: User data persists across sessions
Collaborative Tools: Shared data access and project management

☁️ Cloud-Native

Kubernetes-Native: Built for modern container orchestration
GKE Optimized: Tested and optimized for Google Kubernetes Engine
Helm Charts: Easy deployment and configuration management
CI/CD Ready: GitHub Actions integration for automated deployments

Quick Start

Prerequisites

Google Cloud Platform Account with billing enabled

Local Development Tools:

# macOS
brew install google-cloud-sdk kubectl helm docker

# Ubuntu/Debian
sudo apt-get install google-cloud-sdk kubectl helm docker.io

# CentOS/RHEL
sudo yum install google-cloud-sdk kubectl helm docker

Domain Name (for production deployment)

1. Clone Repository

git clone https://github.com/archetana/cmbcluster.git
cd cmbcluster

2. Setup Environment

# Copy environment template
cp .env.example .env

# Edit configuration
vim .env

Required environment variables:

PROJECT_ID=cambridge-infosys
BASE_DOMAIN=cmbcluster.yourdomain.com
GOOGLE_CLIENT_ID=your-oauth-client-id
GOOGLE_CLIENT_SECRET=your-oauth-secret
SECRET_KEY=your-generated-secret-key

3. Choose Deployment Method

Option A: Local Development

# Start local environment
make dev

# Or using docker-compose directly
docker-compose up --build

Access at: http://localhost:8501

Option B: Production Deployment

# Setup GKE cluster
make setup PROJECT_ID=your-project DOMAIN=your-domain.com

# Deploy application
make deploy

Local Development

Quick Start

# Start all services
docker-compose up --build

# Access points:
# Frontend: http://localhost:8501
# Backend API: http://localhost:8000
# API Docs: http://localhost:8000/docs
# User Environment: http://localhost:8502

Development Commands

# Make the script executable
chmod +x scripts/build-images.sh
chmod +x scripts/setup-cluster.sh
chmod +x scripts/deploy.sh
chmod +x scripts/cleanup.sh
chmod +x scripts/local-dev.sh

# Build images
make build

# Run tests
make test

# View logs
make logs

# Stop services
docker-compose down

# Clean up everything
make clean

File Structure

cmbcluster/
├── README.md                # This file
├── .env.example            # Environment template
├── .gitignore              # Git ignore rules
├── docker-compose.yml      # Local development setup
├── Makefile               # Build and deployment commands
├── backend/               # FastAPI backend service
│   ├── Dockerfile
│   ├── requirements.txt
│   ├── main.py           # Application entry point
│   ├── auth.py           # OAuth authentication
│   ├── pod_manager.py    # Kubernetes pod management
│   ├── config.py         # Configuration settings
│   └── models.py         # Data models
├── frontend/              # Streamlit frontend application
│   ├── Dockerfile
│   ├── requirements.txt
│   ├── main.py           # Main UI application
│   ├── config.py         # Frontend configuration
│   ├── components/       # Reusable UI components
│   │   ├── auth.py
│   │   └── api_client.py
│   └── pages/           # Multi-page UI
│       ├── Dashboard.py
│       ├── Environment.py
│       └── Settings.py
├── user-environment/      # User research environment container
│   ├── Dockerfile
│   ├── requirements.txt
│   └── app.py           # Streamlit research application
├── k8s/                  # Kubernetes manifests
│   ├── namespace.yaml
│   ├── rbac.yaml
│   ├── backend-deployment.yaml
│   ├── frontend-deployment.yaml
│   └── ingress.yaml
├── helm/                 # Helm chart templates
│   ├── Chart.yaml
│   ├── values.yaml
│   └── templates/
│       ├── backend.yaml
│       ├── frontend.yaml
│       └── ingress.yaml
├── scripts/              # Deployment and utility scripts
│   ├── setup-cluster.sh
│   ├── build-images.sh
│   ├── deploy.sh
│   ├── cleanup.sh
│   └── local-dev.sh
└── terraform/            # Infrastructure as code (optional)
    ├── main.tf
    ├── variables.tf
    └── outputs.tf

Production Deployment

1. Setup Google Cloud Infrastructure

# Authenticate with Google Cloud
gcloud auth login
gcloud config set project YOUR_PROJECT_ID

# Setup cluster and infrastructure
./scripts/setup-cluster.sh YOUR_PROJECT_ID

This creates:

GKE cluster with autoscaling (1-10 nodes)
NGINX Ingress Controller with LoadBalancer
cert-manager for automated SSL certificates
Required service accounts and RBAC policies
Storage classes for persistent volumes

2. Configure OAuth

Go to Google Cloud Console
Navigate to APIs & Services > Credentials
Create OAuth 2.0 Client ID

Add authorized redirect URIs:

https://api.yourdomain.com/auth/callback

Update .env with client ID and secret

3. Deploy Application

# Build and push container images
./scripts/build-images.sh YOUR_PROJECT_ID

# Deploy with Helm
./scripts/deploy.sh YOUR_PROJECT_ID yourdomain.com

4. Configure DNS

Point your domain to the ingress IP:

# Get ingress IP
kubectl get ingress -n cmbcluster

# Create DNS records:
# A record: yourdomain.com -> INGRESS_IP
# A record: *.yourdomain.com -> INGRESS_IP  
# A record: api.yourdomain.com -> INGRESS_IP

Usage

For Users

Access Platform: Navigate to https://yourdomain.com
Login: Click "🔐 Login with Google" and authenticate
Launch Environment: Click ":material/rocket_launch: Launch Environment" to create your research pod
Start Research: Access your isolated Streamlit environment with:
- Pre-installed research libraries (pandas, numpy, scipy, matplotlib)
- Persistent workspace storage (/workspace)
- Scientific computing tools (NumPy, SciPy, Matplotlib)
- Data visualization capabilities (Plotly, Seaborn)

User Environment Features

# Pre-installed libraries available in user environments
import numpy as np
import scipy as sp
import matplotlib.pyplot as plt
import pandas as pd
import plotly.express as px
import astropy
import healpy as hp
import camb

# Persistent workspace
workspace_dir = "/workspace"  # Your files persist here

For Administrators

# Monitor deployments
kubectl get pods -n cmbcluster

# View logs
kubectl logs -f deployment/cmbcluster-backend -n cmbcluster
kubectl logs -f deployment/cmbcluster-frontend -n cmbcluster

# Scale deployments
kubectl scale deployment cmbcluster-backend --replicas=5 -n cmbcluster

# List user environments
kubectl get pods -l app=cmbcluster-user-env -n cmbcluster

# Clean up inactive environments
kubectl delete pods -l app=cmbcluster-user-env --field-selector status.phase=Succeeded -n cmbcluster

Configuration

Environment Variables

Variable	Description	Default	Required
`PROJECT_ID`	GCP Project ID	-	✅
`BASE_DOMAIN`	Platform domain	`cmbcluster.local`	✅
`GOOGLE_CLIENT_ID`	OAuth Client ID	-	✅
`GOOGLE_CLIENT_SECRET`	OAuth Secret	-	✅
`SECRET_KEY`	JWT signing key	-	✅
`MAX_INACTIVE_HOURS`	Auto-cleanup time	`1H`	✅
`MAX_USER_PODS`	Pods per user	`1`	✅
`TOKEN_EXPIRE_HOURS`	JWT expiration	`24`	✅
`NAMESPACE`	Kubernetes namespace	`cmbcluster`	✅
`FILE_ENCRYPTION_KEY`	Environment file encryption key	-	⚠️

⚠️ Important: The FILE_ENCRYPTION_KEY is required for production deployments to encrypt uploaded environment files. See ENCRYPTION.md for details.

Resource Limits

Default user environment resources:

userEnvironment:
  defaultResources:
    requests:
      cpu: 100m
      memory: 256Mi
    limits:
      cpu: 2000m
      memory: 4Gi
  storage:
    size: 10Gi
    storageClass: standard-rwo

Helm Configuration

Customize deployment in helm/values.yaml:

# Backend scaling
backend:
  replicaCount: 2
  resources:
    limits:
      cpu: 1000m
      memory: 1Gi

# Frontend scaling  
frontend:
  replicaCount: 2
  
# Auto-scaling
autoscaling:
  enabled: true
  minReplicas: 1
  maxReplicas: 10

Architecture Details

Component Responsibilities

🌐 Proxy (NGINX Ingress)

Route Info Send: Forward user requests to Hub
User Routing: Direct authenticated users to their pods
SSL Termination: Handle HTTPS certificates
Load Balancing: Distribute traffic across replicas

🎯 Hub (Backend Service)

Authenticate User: Google OAuth integration
Signed Out User Redirect: Send unauthenticated users to login
Volume Provide/Pod Create: Provision user resources
User Redirect: Route users to their environments
Cull Pods If Stale: Clean up inactive environments

🔬 Pods + Volumes

Image Pull: Download user environment containers
User Session: Maintain persistent workspace state
Resource Isolation: Dedicated CPU/memory/storage per user
Data Persistence: User files survive pod restarts

Data Flow

1. User → Proxy → Hub (check authentication)
2. Hub → Google OAuth (if not authenticated)  
3. Hub → Create/Find User Pod
4. Proxy → User Pod (direct traffic)
5. User Pod → Streamlit App (research environment)

Monitoring

Health Checks

# Check all services
kubectl get pods -n cmbcluster

# Backend health
curl https://api.yourdomain.com/health

# Frontend health  
curl https://yourdomain.com/_stcore/health

Logs

# Backend logs
kubectl logs -f deployment/cmbcluster-backend -n cmbcluster

# Frontend logs
kubectl logs -f deployment/cmbcluster-frontend -n cmbcluster

# User environment logs
kubectl logs  -n cmbcluster

# Ingress logs
kubectl logs -f deployment/ingress-nginx-controller -n ingress-nginx

Metrics

The platform exposes Prometheus metrics:

# Backend metrics
cmbcluster_active_users
cmbcluster_pods_created_total
cmbcluster_authentication_requests_total

# Resource metrics  
cmbcluster_cpu_usage
cmbcluster_memory_usage
cmbcluster_storage_usage

Security

Authentication Flow

sequenceDiagram
    participant U as User
    participant P as Proxy
    participant H as Hub  
    participant G as Google OAuth
    
    U->>P: Access platform
    P->>H: Check authentication
    H->>G: Redirect to OAuth
    G->>H: Return user info
    H->>H: Create JWT token
    H->>P: Redirect with token
    P->>U: Access granted

Security Features

TLS 1.3: All traffic encrypted in transit
Network Policies: Pod-to-pod communication restrictions
Pod Security: Non-root containers, read-only filesystems
RBAC: Kubernetes role-based access control
Secrets Management: Encrypted credential storage

Data Protection

Workspace Isolation: Each user has dedicated storage
Encryption at Rest: Persistent volumes encrypted
Data Retention: Configurable cleanup policies
Backup Support: Regular workspace backups

Troubleshooting

Common Issues

Pod Won't Start

# Check pod status
kubectl get pods -n cmbcluster
kubectl describe pod  -n cmbcluster
kubectl logs  -n cmbcluster

# Common causes:
# - Image pull errors
# - Resource constraints  
# - Storage mounting issues

Authentication Errors

# Check OAuth configuration
kubectl get secret cmbcluster-secrets -n cmbcluster -o yaml

# Verify redirect URLs in Google Cloud Console
# Ensure domain matches configuration

Ingress Issues

# Check ingress status
kubectl get ingress -n cmbcluster
kubectl describe ingress cmbcluster-ingress -n cmbcluster

# Verify certificates
kubectl get certificates -n cmbcluster
kubectl describe certificate cmbcluster-tls -n cmbcluster

Storage Problems

# Check persistent volumes
kubectl get pv
kubectl get pvc -n cmbcluster

# Storage class issues
kubectl get storageclass

Debug Commands

# Get all resources
kubectl get all -n cmbcluster

# Check events
kubectl get events -n cmbcluster --sort-by='.lastTimestamp'

# Pod shell access (for debugging)
kubectl exec -it  -n cmbcluster -- /bin/bash

# Port forwarding for local access
kubectl port-forward service/cmbcluster-backend 8000:80 -n cmbcluster

Testing

Unit Tests

# Backend tests
cd backend
python -m pytest tests/

# Frontend tests  
cd frontend
python -m pytest tests/

Integration Tests

# End-to-end testing
pytest tests/integration/

# Load testing
locust -f tests/load/locustfile.py

Development Testing

# Test local deployment
make dev
curl http://localhost:8000/health
curl http://localhost:8501/_stcore/health

Contributing

We welcome contributions! Please see our Contributing Guide for details.

Development Workflow

# 1. Fork and clone repository
git clone https://github.com/yourusername/cmbcluster.git
cd cmbcluster

# 2. Create feature branch
git checkout -b feature/your-feature-name

# 3. Make changes and test locally
make dev
make test

# 4. Commit and push
git commit -m "Add your feature"
git push origin feature/your-feature-name

# 5. Create pull request

Code Standards

Python: Follow PEP 8, use Black formatter
Docker: Multi-stage builds, minimal base images
Kubernetes: Follow security best practices
Documentation: Update README and inline docs

Roadmap

Near Term (Q1 2025)

GPU Support: CUDA-enabled environments for ML workloads
Advanced Monitoring: Grafana dashboards and alerting
User Quotas: Storage and compute limits per user
Backup System: Automated workspace backups

Medium Term (Q2-Q3 2025)

Multi-cloud Support: AWS EKS and Azure AKS deployment
Jupyter Integration: Built-in Jupyter notebook support
Collaborative Features: Real-time collaboration tools
Data Pipeline Integration: Connect with external data sources

Long Term (Q4 2025+)

Enterprise SSO: SAML and LDAP integration
Advanced Analytics: Usage analytics and cost optimization
Custom Environments: User-defined container images
Federation: Multi-cluster deployments

Support

Getting Help

📚 Documentation: GitHub Wiki
🐛 Bug Reports: Issue Tracker
💬 Discussions: GitHub Discussions
📧 Email: [email protected]

Community

Slack: Join our CMBCluster Slack
Monthly Meetings: First Friday of each month at 10 AM PST
Office Hours: Wednesdays 2-3 PM PST

License

This project is licensed under the MIT License - see the LICENSE file for details.

Acknowledgments

Built on the JupyterHub architecture pattern
Inspired by the research community needs
Special thanks to early adopters and contributors
Container orchestration powered by Kubernetes

CMBCluster - Empowering research through scalable, secure, and collaborative computing environments.

For more information, visit our GitHub repository or contact us at [email protected].

[1] https://pplx-res.cloudinary.com/image/private/user_uploads/55150389/b6a3b9f3-c4a1-40cc-a9f2-7cca9d35b398/image.jpg

Name		Name	Last commit message	Last commit date
Latest commit History 38 Commits
backend		backend
frontend		frontend
helm		helm
k8s		k8s
scripts		scripts
terraform		terraform
user-environment		user-environment
.env.example		.env.example
.gitignore		.gitignore
Makefile		Makefile
README.md		README.md
cmbcluster-pod-manager.yaml		cmbcluster-pod-manager.yaml
compose.env.example		compose.env.example
compose.yml		compose.yml
logs		logs
rbac1.yaml		rbac1.yaml

CMBAgents/cmbcluster

Folders and files

Latest commit

History

Repository files navigation

CMBCluster

Architecture

Features

🔐 Enterprise Security

🚀 Scalable Infrastructure

🔬 Research-Focused

☁️ Cloud-Native

Quick Start

Prerequisites

1. Clone Repository

2. Setup Environment

3. Choose Deployment Method

Option A: Local Development

Option B: Production Deployment

Local Development

Quick Start

Development Commands

File Structure

Production Deployment

1. Setup Google Cloud Infrastructure

2. Configure OAuth

3. Deploy Application

4. Configure DNS

Usage

For Users

User Environment Features

For Administrators

Configuration

Environment Variables

Resource Limits

Helm Configuration

Architecture Details

Component Responsibilities

🌐 Proxy (NGINX Ingress)

🎯 Hub (Backend Service)

🔬 Pods + Volumes

Data Flow

Monitoring

Health Checks

Logs

Metrics

Security

Authentication Flow

Security Features

Data Protection

Troubleshooting

Common Issues

Pod Won't Start

Authentication Errors

Ingress Issues

Storage Problems

Debug Commands

Testing

Unit Tests

Integration Tests

Development Testing

Contributing

Development Workflow

Code Standards

Roadmap

Near Term (Q1 2025)

Medium Term (Q2-Q3 2025)

Long Term (Q4 2025+)

Support

Getting Help

Community

License

Acknowledgments

About

Resources

Uh oh!

Stars

Watchers

Forks

Releases

Packages