Quickstart

Use this guide to get Open Codelabs running in about 5 minutes.

Prerequisites

Minimum requirements:

• Docker (recommended), or
• Bun + Rust for local development

Run with Docker (recommended)

This is the simplest option. You only need Docker installed.

1. Clone the repository

git clone https://github.com/JAICHANGPARK/open-codelabs.git
cd open-codelabs

2. Start with Docker Compose

docker compose up --build

The first run may take a few minutes while images build.

2-1. Run with Prebuilt Images (Faster Start)

To skip the local build process, you can use the published images from GitHub Container Registry.

# Setup environment variables (Defaults to ghcr.io/jaichangpark/ images)
cp .env.sample .env

# Run using the prebuilt image compose file
docker compose -f docker-compose.images.yml up

3. Open in your browser

Once the build is done:

• Facilitator (admin): http://localhost:5173/login
• ID: admin
• PW: admin
• Attendee: http://localhost:5173

Start with the CLI

If you prefer to begin from the terminal, install oc and use the guided onboarding flow with arrow-key menus, Space-based multi-selects, and hidden password prompts.

cargo install --path backend --bin oc
oc init

If you already know you want a local stack, you can start it directly:

oc run --open

• Install, remove, and cleanup steps are documented in the Installation Guide.
• The full command surface is listed in the CLI Reference.

Run locally for development

If you are developing, you can run everything locally.

Run the backend

cd backend

# Set environment variables
cat > .env << EOF
DATABASE_URL=sqlite:data/sqlite.db?mode=rwc
ADMIN_ID=admin
ADMIN_PW=admin123
EOF

# Create database directory
mkdir -p data

# Start the server
cargo run

The backend runs at http://localhost:8080.

Run the frontend

In a new terminal:

cd frontend

# Install dependencies
bun install

# Start the dev server
bun run dev

The frontend runs at http://localhost:5173.

Create your first codelab

1. Log in as admin

1. Go to http://localhost:5173/login
2. Log in with the default credentials:
3. ID: admin
4. PW: admin123

2. Create a codelab

1. Click "Create New Codelab"
2. Fill in details:
3. Title: "My First Codelab"
4. Description: "Build a web server with Rust"
5. Author: "Jane Doe"
6. Click "Create"

3. Add steps

Open the newly created codelab card to edit:

1. Click "Add Step"
2. Enter step details:
3. Title: "Project Setup"
4. Content: Write in Markdown

# Project Setup

Create a new Rust project:

```bash
cargo new my-web-server
cd my-web-server

## Add dependencies

Add these dependencies to Cargo.toml:

[dependencies]
axum = "0.7"
tokio = { version = "1.0", features = ["full"] }

```

1. Click "Save"

4. Test as an attendee

1. Open a new incognito window (or another browser) and visit http://localhost:5173
2. Select the codelab
3. Enter your name and attendee code
4. Follow the steps

Next steps

You have created your first codelab. Explore the following:

• Installation Guide - detailed setup options
• CLI Reference - oc install, removal, connect, and runtime commands
• Create Your First Codelab - advanced features
• Public Deployment - expose locally via ngrok/bore/cloudflare
• API Reference - automation and integrations

Troubleshooting

Docker containers do not start

# Stop existing containers
docker compose down

# Clean volumes
docker compose down -v

# Restart
docker compose up --build

Port is already in use

Update the ports in docker-compose.yml:

services:
  frontend:
    ports:
      - "3000:5173"  # Use 3000 instead of 5173
  backend:
    ports:
      - "3080:8080"  # Use 3080 instead of 8080

Database errors

# Reset backend data
rm -rf backend/data/sqlite.db

# Restart
docker compose restart backend

For more troubleshooting, see the FAQ.