퍼실리테이터 사용 가이드¶

이 가이드는 Open Codelabs를 사용하여 핸즈온 세션을 운영하는 퍼실리테이터(강사/진행자)를 위한 매뉴얼입니다.

1. 시작하기 전에¶

필요한 준비사항¶

Open Codelabs 시스템 설치 완료 (설치 가이드 참고)
핸즈온 콘텐츠 (Markdown 형식)
세션 진행 환경 (로컬 또는 공개 서버)

퍼실리테이터 역할¶

코드랩(Codelab) 생성 및 관리
세션 운영 및 진행 상황 모니터링
참가자 진행도 확인
실시간 피드백 수집

2. 시스템 접속하기¶

로컬 환경에서 시작¶

# Docker Compose로 시작
docker-compose up --build

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

Admin 페이지 접속¶

브라우저에서 http://localhost:5173 접속
좌측 상단 메뉴에서 "Admin" 클릭
퍼실리테이터 전용 관리 페이지 진입

3. 코드랩 생성하기¶

3-1. 수동으로 코드랩 생성¶

Admin 페이지에서 "Create New Codelab" 버튼 클릭
다음 정보 입력:
Title: 코드랩 제목 (예: "Docker 시작하기")
Description: 간단한 설명
Duration: 예상 소요 시간 (분 단위)
Tags: 관련 키워드 (쉼표로 구분)

Markdown 콘텐츠 작성:

# Step 1: 환경 설정

Docker를 설치하고 확인해봅시다.

```bash
docker --version

# Step 2: 첫 번째 컨테이너 실행

Hello World 컨테이너를 실행해봅시다.

docker run hello-world

``` 4. "Save" 버튼을 눌러 저장

3-2. AI로 코드랩 자동 생성 (Gemini 연동)¶

Admin 페이지에서 "AI Codelab Generator" 클릭
원하는 주제 입력 (예: "Kubernetes 기초")
생성 모드에서 일반 모드 또는 프로 모드 선택
AI가 자동으로 단계별 콘텐츠 생성
생성된 내용 확인 후 필요시 수정
"Save" 버튼으로 저장

AI 생성 팁

구체적인 주제와 목표 레벨을 명시하면 더 정확한 콘텐츠가 생성됩니다
예: "초보자를 위한 Python Flask 웹 개발 입문"

4. 코드랩 관리하기¶

코드랩 목록 보기¶

Admin 페이지에서 생성된 모든 코드랩 확인
각 코드랩의 상태, 참가자 수, 완료율 확인

코드랩 수정하기¶

Admin 페이지에서 수정할 코드랩 선택
"Edit" 버튼 클릭
내용 수정 후 "Update" 저장

코드랩 삭제하기¶

Admin 페이지에서 삭제할 코드랩 선택
"Delete" 버튼 클릭
확인 후 삭제 (복구 불가능)

5. 세션 운영하기¶

5-1. 참가자에게 접속 정보 공유¶

로컬 네트워크에서 진행하는 경우¶

접속 URL: http://YOUR_LOCAL_IP:5173

외부 접속이 필요한 경우 (ngrok/bore/cloudflare 사용)¶

./run-public.sh --ngrok
# 또는
./run-public.sh --bore
# 또는
./run-public.sh --cloudflare

스크립트 실행 후: - QR 코드가 자동 생성됨 - 참가자들에게 QR 코드를 스크린에 띄워 공유 - 또는 생성된 Public URL을 직접 공유

보안 주의

Public URL은 세션 종료 후 반드시 종료하세요.

5-2. 참가자 모니터링¶

Admin 페이지에서 실시간으로 확인 가능: - 참가자 수: 현재 접속 중인 참석자 - 진행 상황: 각 단계별 완료한 참가자 비율 - 피드백: 참가자들이 남긴 질문 및 피드백

5-3. 실시간 도움 제공¶

참가자가 특정 단계에서 막혔을 때: 1. Admin 대시보드에서 진행 상황 확인 2. 해당 단계의 완료율이 낮다면 추가 설명 제공 3. 필요시 단계 내용을 즉시 수정하여 개선

6. 진행 상황 확인하기¶

대시보드에서 확인 가능한 정보¶

전체 참가자 수
각 단계별 완료율 (Progress %)
평균 소요 시간
피드백 및 질문 내역

참가자 개별 진행도 확인¶

Admin 페이지에서 "Participants" 클릭
각 참가자의 현재 진행 단계 확인
진행이 느린 참가자 파악 및 지원

7. 피드백 수집 및 분석¶

실시간 피드백 확인¶

Admin 페이지 "Feedback" 섹션에서 확인
참가자들이 각 단계에서 남긴 의견 및 질문 확인

세션 종료 후¶

전체 완료율 확인
어려웠던 단계 분석 (완료율이 낮은 단계)
다음 세션 개선을 위한 자료로 활용

8. 팁 및 모범 사례¶

세션 시작 전¶

[ ] 코드랩 콘텐츠를 미리 테스트해보세요
[ ] 예상 소요 시간을 현실적으로 설정하세요
[ ] 필요한 사전 준비 사항(소프트웨어, 계정 등)을 미리 공지하세요

세션 진행 중¶

[ ] 첫 단계를 함께 진행하여 시스템 사용법을 안내하세요
[ ] 진행 상황을 주기적으로 확인하고 필요시 속도 조절하세요
[ ] 질문을 적극적으로 받고 실시간 피드백을 활용하세요

세션 종료 후¶

[ ] 참가자들에게 완료 인증 또는 자료를 제공하세요
[ ] 피드백을 분석하여 다음 세션을 개선하세요
[ ] 코드랩 콘텐츠를 업데이트하세요

9. 문제 해결¶

참가자가 접속을 못 하는 경우¶

방화벽 설정 확인
Public URL이 제대로 생성되었는지 확인
네트워크 연결 상태 확인

시스템이 느린 경우¶

동시 접속자 수가 너무 많지 않은지 확인
서버 리소스 (CPU, 메모리) 확인
Docker 컨테이너 재시작 시도

콘텐츠가 제대로 표시되지 않는 경우¶

Markdown 문법 오류 확인
코드 블록의 언어 지정 확인 (bash,python 등)
브라우저 캐시 삭제 후 재접속

10. 추가 리소스¶

준비 완료!

이제 성공적인 핸즈온 세션을 운영할 준비가 되었습니다! 🎉