Open Codelabs (Hands-on System)¶

Open-Codelabs: Hands-on System is an open-source platform designed to run Google Codelab-style hands-on sessions. It supports both facilitator and attendee roles, lets you author content with Markdown or AI, and provides self-hosted and serverless deployment options.

Overview¶

This project is an interactive hands-on platform where educators (Facilitators) create step-by-step guides and attendees learn at their own pace. It is built on a SaaS-friendly architecture and manages content through Markdown and AI workflows. Built-in i18n support is provided.

Key Features¶

Role-based workflow¶

Facilitator (admin): create and manage codelabs, edit content, manage attendees
Attendee: follow steps, track progress, request help

AI-assisted content creation¶

Gemini-based codelab generator (source code or docs input)
Prep guide generation and centralized materials management

Codelab workspace (optional)¶

code-server based workspace
Step snapshots (branch/folder modes) and downloads

Completion and verification¶

Require quizzes and feedback for completion
Auto-issued certificates with verification URLs

Google Codelab-style UI¶

Familiar interface
Responsive layout for mobile/tablet
Dark mode support

Real-time interaction¶

WebSocket-based chat
1:1 DM
Help request queue and management
Live attendee progress monitoring
Submission panel and certificate raffle

Markdown-based content¶

Simple authoring
Code highlighting
Image upload and management
Import/Export support

Deployment flexibility¶

One-command Docker deployment
Public exposure via ngrok/bore/cloudflared
QR code invites
Rust + SQLite self-hosting or Firebase/Supabase serverless mode
Prebuilt images via docker-compose.images.yml

Tech Stack¶

Frontend¶

Framework: SvelteKit 5 (Vite + TypeScript)
Runtime: Bun
Styling: Tailwind CSS 4.0
State: Svelte Runes
i18n: svelte-i18n
Markdown: marked & dompurify
Icons: Lucide Svelte
QR Code: svelte-qrcode

Backend¶

Language: Rust
Framework: Axum (Tokio async runtime)
Database: SQLite with SQLx
WebSocket: Axum WebSocket support
Serialization: Serde (JSON)

Cloud (serverless options)¶

Firebase: Hosting, Firestore, Storage
Supabase: Postgres, Auth, Storage, Realtime

DevOps¶

Docker & Docker Compose
Multi-stage builds
ngrok/bore/cloudflared for tunneling

Quickstart¶

The simplest way to run the full stack is via Docker:

docker compose up --build

Frontend: http://localhost:5173
Backend API: http://localhost:8080

To run with prebuilt images:

cp .env.sample .env
docker compose -f docker-compose.images.yml up

For a CLI-first flow, run oc init to start a local stack or connect to an existing server through prompts. Installation and removal details live in the Installation Guide, and the full command surface is documented in the CLI Reference.

Documentation Map¶

Getting Started: Quickstart and setup
CLI Reference: oc install, connect, auth, and runtime commands
Self-Hosting: Docker, local dev, public deployment
Serverless Deployment: Firebase guide
Serverless Deployment: Supabase guide
Specifications: Features and API reference
Architecture: System design docs
Code Guide: Examples and usage
User Guide: Facilitator and attendee features
Contributing: How to contribute
FAQ: Common questions