ContainrLab is a production-grade containerization training platform leveraging Docker-in-Docker isolation, WebSocket-based terminal emulation, and Google Gemini AI integration. Deploy multi-stage Dockerfiles, orchestrate container lifecycles, and execute commands in ephemeral sandbox environments—all delivered through a browser-based interface with zero client-side dependencies. The platform implements automated test harnesses for instant feedback, AI-driven contextual assistance, and supports full container runtime operations without local infrastructure requirements.

Showcased at MLH Global Hack Week

• Hands-On Labs - Write real Docker code with practical, project-based exercises → View Labs
• Instant Validation - Automated judges test your solutions in real-time → How it works
• AI Assistant - Contextual hints powered by Google Gemini → Learn more
• Browser Terminal - Full bash terminal with Docker-in-Docker capabilities → Architecture
• Integrated Editor - Edit Dockerfiles and application code directly in the browser → See UI
• Secure Isolation - Individual containers with resource limits for each session → Security model

1. Start Lab → User selects lab, API creates session record in database
2. Spawn Environment → RunnerD orchestrates isolated Docker container with Docker-in-Docker
3. Interactive Terminal → WebSocket establishes real-time bidirectional connection
4. Code & Build → User writes Dockerfiles, builds images, runs containers in sandbox
5. Automated Validation → Judge executes test harness against solution requirements
6. Session Cleanup → Environment auto-expires after timeout, resources freed

• Isolation: Each session runs in isolated Docker container with separate network namespace
• Resource Limits: CPU and memory constraints enforced per session container
• Network Isolation: Sessions cannot communicate with each other
• Authentication: GitHub OAuth with NextAuth.js session management
• Secrets: Environment variables injected at runtime from secure parameter store

graph TB
    User[👤 User Browser]
    
    Web[🌐 Next.js Frontend<br/>Port 3000<br/>- React UI<br/>- Auth<br/>- Terminal<br/>- File Editor]
    
    API[⚡ FastAPI Backend<br/>Port 8000<br/>- REST API<br/>- WebSocket Proxy<br/>- Session Management<br/>- Judge Orchestration]
    
    RunnerD[🔧 RunnerD Service<br/>Port 8080<br/>- Session Containers<br/>- Docker-in-Docker<br/>- File Operations]
    
    Session1[🐋 Session Container<br/>sess-abc123<br/>- Docker Daemon<br/>- Workspace<br/>- Bash Terminal]
    Session2[🐋 Session Container<br/>sess-xyz789<br/>- Docker Daemon<br/>- Workspace<br/>- Bash Terminal]
    
    GitHub[🔐 GitHub OAuth]
    Gemini[🤖 Google Gemini AI]
    DB[(💾 SQLite Database<br/>- Users<br/>- Sessions<br/>- Attempts)]
    
    User -->|HTTPS| Web
    User -.->|OAuth Login| GitHub
    GitHub -.->|User Profile| User
    
    Web -->|API Requests| API
    Web <-->|WebSocket Terminal| API
    
    API -->|Authenticate| GitHub
    API -->|AI Hints| Gemini
    API -->|Read/Write| DB
    
    API -->|Create Session| RunnerD
    API -->|Execute Commands| RunnerD
    API -->|Build Docker| RunnerD
    API -->|File Operations| RunnerD
    API <-->|Terminal WebSocket| RunnerD
    
    RunnerD -->|Spawn Container| Session1
    RunnerD -->|Spawn Container| Session2
    RunnerD -->|Manage Lifecycle| Session1
    RunnerD -->|Manage Lifecycle| Session2
    
    classDef frontend fill:#4a90e2,stroke:#2d5a8c,color:#fff
    classDef backend fill:#50c878,stroke:#2d7a4a,color:#fff
    classDef runner fill:#f39c12,stroke:#c87f0a,color:#fff
    classDef session fill:#e74c3c,stroke:#c0392b,color:#fff
    classDef external fill:#9b59b6,stroke:#6c3483,color:#fff
    classDef storage fill:#34495e,stroke:#2c3e50,color:#fff
    
    class Web frontend
    class API backend
    class RunnerD runner
    class Session1,Session2 session
    class GitHub,Gemini external
    class DB storage

View detailed architecture documentation →

• ECS Fargate for stateless services (API, Web)
• ECS on EC2 for privileged workloads (Runner with Docker-in-Docker)
• Application Load Balancer for HTTPS traffic routing and SSL termination
• Container Registry for Docker image storage and distribution
• Managed Secrets Storage for secure environment variable injection

• API/Web: Serverless compute with auto-scaling based on demand
• Runner: Dedicated compute instances with container orchestration
• Session Isolation: 1.5GB RAM, 1 vCPU per sandbox environment
• Session Timeout: 45-minute auto-expiration with grace period

• Region: Multi-AZ deployment in US East for high availability
• Images: AMD64 (x86_64) architecture for cross-platform compatibility
• CI/CD: Automated build, test, and deployment via GitHub Actions
• Infrastructure: Optimized for low-volume production workloads

No installation required. Access the platform immediately with GitHub authentication.

1. Visit https://containrlab.sanjaybaskaran.dev
2. Sign in with GitHub OAuth
3. Select a lab (Lab 1 recommended for beginners)
4. Click "Start Session" to launch your isolated environment

Start Learning →

Run the full stack on your machine with Docker Compose.

# Clone repository
git clone https://github.com/sanjayb-28/ContainrLab.git
cd ContainrLab

# Set up secrets
echo "your-github-client-id" > compose/secrets/GITHUB_CLIENT_ID.txt
echo "your-github-client-secret" > compose/secrets/GITHUB_CLIENT_SECRET.txt
echo "your-gemini-api-key" > compose/secrets/GEMINI_API_KEY.txt  # Optional

# Start services
docker compose -f compose/docker-compose.yml up

# Access at http://localhost:3000

Deploy a production instance to AWS ECS with automated CI/CD pipelines.

Browse all documentation →

Progressive learning path from beginner to advanced concepts:

Each lab includes:

• Clear requirements and learning objectives
• Starter workspace (or empty canvas)
• Automated validation with detailed feedback
• AI-powered hints when you're stuck
• Reference solution with explanations

View complete lab catalog →

View detailed architecture →

Contributions are welcome! Key areas for contribution:

• New Labs - Create additional Docker learning content
• Bug Fixes - Resolve issues and improve stability
• Features - Develop new platform capabilities
• Documentation - Enhance guides and examples
• Testing - Expand test coverage

Read the Contributing Guide →

• ✅ Production: Fully deployed at containrlab.sanjaybaskaran.dev
• ✅ CI/CD: Automated testing and deployment via GitHub Actions
• ✅ Labs: 3 Docker labs (beginner to advanced)
• 🚧 Roadmap: More labs, Kubernetes content, team features

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

• Issues: GitHub Issues
• Discussions: GitHub Discussions
• Email: sanjay.baskaran@colorado.edu