설치 가이드¶

Open Codelabs를 설치하는 다양한 방법을 소개합니다.

시스템 요구사항¶

최소 요구사항¶

메모리: 2GB RAM
디스크: 1GB 여유 공간
OS: Linux, macOS, Windows (WSL2)

소프트웨어 요구사항¶

Docker (권장)로컬 개발Podman

Docker Engine 20.10+
Docker Compose v2.0+

Rust 1.75+
Bun 1.0+
SQLite 3.35+

Podman 4.0+
podman-compose 1.0+

CLI (`oc`) 설치¶

oc CLI로 이미 실행 중인 Open Codelabs 서버를 관리할 수 있고, 로컬 스택도 바로 띄울 수 있습니다.

가장 쉬운 시작 방법은 인터랙티브 온보딩입니다.

oc init

oc init은 로컬 스택 실행 또는 기존 서버 연결을 인터랙티브 TUI로 안내하고, 이어서 profile 저장과 oc auth login까지 연결해줍니다. 선택형 단계에서는 화살표로 이동하고, 멀티 선택 단계에서는 스페이스로 토글한 뒤 엔터로 다음 단계로 넘어갑니다.

소스에서 설치¶

git clone https://github.com/JAICHANGPARK/open-codelabs.git
cd open-codelabs
cargo install --path backend --bin oc

설치 후 확인:

oc --help

로컬 release 바이너리 빌드¶

cd backend
cargo build --release --bin oc
./target/release/oc --help

CLI만으로 로컬 스택 실행¶

oc run --open

oc run은 다음을 자동으로 처리합니다.

docker 또는 podman 감지
엔진이 없거나 실행 중이 아니면 설치/시작 방법 안내
~/.open-codelabs/runtime/local-stack/compose.yml 생성
퍼블리시된 frontend/backend 이미지를 SQLite 기본 설정으로 실행
플래그 없이 실행하면 인터랙티브 터미널에서 화살표/스페이스 기반 guided setup을 시작

자주 쓰는 옵션:

# 최신 이미지 먼저 pull
oc run --pull

# PostgreSQL 포함 실행
oc run --postgres

# 엔진 강제 선택
oc run --engine docker
oc run --engine podman

실행 후 관리 명령:

oc ps
oc logs --service backend --tail 200 --no-follow
oc restart --service frontend
oc down
oc down --volumes

실행 후 첫 연결¶

oc connect add --name local --url http://localhost:8080 --runtime backend --activate
oc auth login
oc codelab list

또는:

oc connect add --interactive

를 사용하면 profile 이름, URL, runtime을 질문형으로 입력할 수 있습니다. oc connect use도 TTY에서 --name 없이 실행하면 저장된 profile 목록에서 바로 선택할 수 있습니다.

기본적으로 세션은 ~/.open-codelabs/ 아래에 저장됩니다.

지원하는 전체 명령군과 최신 usage는 CLI 레퍼런스에서 확인할 수 있습니다.

CLI (`oc`) 삭제와 정리¶

CLI를 제거할 때는 설치 방식과 로컬 런타임 사용 여부를 함께 확인하면 됩니다.

1. `oc run`으로 띄운 로컬 스택 중지 및 데이터 정리¶

oc down
oc down --volumes

oc down은 컨테이너만 중지하고 compose 런타임을 내립니다.
oc down --volumes는 oc run이 만든 로컬 bind mount 데이터도 함께 제거합니다.

2. Cargo로 설치한 CLI 삭제¶

cargo uninstall backend

3. 수동으로 복사한 바이너리 삭제¶

cargo build --release --bin oc로 직접 빌드했다면 macOS/Linux에서는 backend/target/release/oc, Windows에서는 backend\target\release\oc.exe를 삭제합니다.
GitHub Release나 별도 다운로드 바이너리를 사용했다면 PATH에 복사한 oc 또는 oc.exe 파일을 삭제합니다.

4. 설정, 세션, 런타임 파일 정리¶

rm -rf ~/.open-codelabs

Windows PowerShell에서는:

Remove-Item -Recurse -Force "$HOME\\.open-codelabs"

~/.open-codelabs/에는 profile, 세션, browser auth state, local runtime metadata가 저장됩니다.
Windows에서는 사용자 프로필 디렉터리 아래의 .open-codelabs 경로를 정리하면 됩니다.

5. 제거 후 확인¶

which oc
oc --help

Windows PowerShell에서는:

where.exe oc
oc --help

which oc가 아무 경로도 출력하지 않으면 제거가 완료된 상태입니다.
셸 캐시가 남아 있으면 새 터미널을 열거나 hash -r을 실행하세요.
Windows에서는 where.exe oc가 아무 경로도 출력하지 않으면 PATH에서 제거된 상태입니다.

Docker로 설치하기¶

Docker는 가장 간단하고 권장되는 설치 방법입니다.

1. Docker 설치¶

LinuxmacOSWindows

# Ubuntu/Debian
curl -fsSL https://get.docker.com -o get-docker.sh
sudo sh get-docker.sh

# Docker Compose 설치 (v2 기준 docker-compose-plugin 권장)
sudo apt-get install docker-compose-plugin

Docker Desktop for Mac을 다운로드하여 설치합니다.

Docker Desktop for Windows를 다운로드하여 설치합니다.

WSL2를 사용하는 것을 권장합니다.

Docker Desktop에는 Docker Compose가 기본 포함됩니다. Linux는 docker-compose-plugin 설치가 필요할 수 있습니다. 이제는 docker compose 명령어를 사용합니다. (이전의 docker-compose는 V1 방식입니다)

2. 프로젝트 클론¶

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

3. 환경 변수 설정 (선택사항)¶

기본 설정으로도 실행 가능하지만, 관리자 계정을 변경하고 싶다면:

# docker-compose.yml 편집
nano docker-compose.yml

services:
  backend:
    environment:
      - DATABASE_URL=sqlite:/app/data/sqlite.db?mode=rwc
      - ADMIN_ID=your_admin_id        # 변경
      - ADMIN_PW=your_secure_password # 변경

4. 실행¶

docker compose up -d

-d: 백그라운드에서 실행

5. 로그 확인¶

# 모든 서비스 로그
docker compose logs -f

# Backend만
docker compose logs -f backend

# Frontend만
docker compose logs -f frontend

6. 중지 및 시작¶

# 중지
docker compose stop

# 시작
docker compose start

# 중지 및 컨테이너 제거
docker compose down

# 볼륨까지 제거 (데이터 삭제)
docker compose down -v

Podman으로 설치하기¶

Docker 대신 Podman을 사용하는 경우:

1. Podman 설치¶

Fedora/RHELUbuntumacOS

sudo dnf install podman podman-compose

sudo apt-get install podman podman-compose

brew install podman podman-compose
podman machine init
podman machine start

2. 실행¶

podman-compose up -d

나머지 명령어는 docker compose 대신 podman-compose를 사용하면 됩니다.

로컬 개발 환경 설치¶

개발자를 위한 상세 설치 가이드입니다.

1. Rust 설치¶

curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
source $HOME/.cargo/env

# 버전 확인
rustc --version
cargo --version

2. Bun 설치¶

curl -fsSL https://bun.sh/install | bash

# 버전 확인
bun --version

3. SQLite 설치¶

LinuxmacOSWindows

# Ubuntu/Debian
sudo apt-get install sqlite3 libsqlite3-dev

# Fedora
sudo dnf install sqlite sqlite-devel

brew install sqlite

SQLite는 대부분의 Windows 시스템에 기본 포함되어 있습니다.

4. 프로젝트 클론 및 설정¶

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

5. Backend 설정¶

cd backend

# .env 파일 생성
cat > .env << EOF
DATABASE_URL=sqlite:data/sqlite.db?mode=rwc
ADMIN_ID=admin
ADMIN_PW=admin123
RUST_LOG=backend=debug,tower_http=debug
EOF

# 데이터 디렉토리 생성
mkdir -p data

# 의존성 체크 (선택사항)
cargo check

# 실행
cargo run

Backend는 http://localhost:8080에서 실행됩니다.

6. Frontend 설정¶

새 터미널 창에서:

cd frontend

# 의존성 설치
bun install

# 환경 변수 설정 (선택사항)
cat > .env << EOF
VITE_API_URL=http://localhost:8080
EOF

# 개발 서버 실행
bun run dev

Frontend는 http://localhost:5173에서 실행됩니다.

프로덕션 빌드¶

Docker 프로덕션 이미지¶

# 프로덕션 이미지 빌드
docker compose -f docker-compose.prod.yml build

# 실행
docker compose -f docker-compose.prod.yml up -d

로컬 프로덕션 빌드¶

Backend¶

cd backend

# Release 빌드
cargo build --release

# 실행
./target/release/backend

Frontend¶

cd frontend

# 프로덕션 빌드
bun run build

# 프리뷰
bun run preview

SQLx CLI 설치 (개발자용)¶

데이터베이스 마이그레이션을 관리하려면:

cargo install sqlx-cli --no-default-features --features sqlite

# 마이그레이션 실행
cd backend
sqlx migrate run

# 마이그레이션 되돌리기
sqlx migrate revert

# 새 마이그레이션 생성
sqlx migrate add <migration_name>

데이터베이스 초기화¶

데이터베이스를 초기 상태로 되돌리려면:

# Docker 사용 시
docker compose down -v
rm -rf backend/data/sqlite.db
docker compose up -d

# 로컬 개발 시
rm -rf backend/data/sqlite.db
cargo run

환경 변수 전체 목록¶

Backend¶

변수	설명	기본값	필수
`DATABASE_URL`	SQLite 데이터베이스 경로	`sqlite:data/sqlite.db?mode=rwc`	✅
`ADMIN_ID`	관리자 ID	`admin`	✅
`ADMIN_PW`	관리자 비밀번호	`admin123`	✅
`RUST_LOG`	로그 레벨	`backend=debug,tower_http=debug`	❌

Frontend¶

변수	설명	기본값	필수
`VITE_API_URL`	Backend API URL	`http://localhost:8080`	❌
`PORT`	프론트엔드 포트	`5173`	❌
`HOST`	바인딩 호스트	`0.0.0.0`	❌

검증¶

설치가 완료되었는지 확인:

1. Health Check¶

# Backend health check
curl http://localhost:8080/api/codelabs

# 응답 예시
[]

2. Frontend 접속¶

브라우저에서 http://localhost:5173 접속

3. 관리자 로그인¶

http://localhost:5173/login 접속
설정한 자격증명으로 로그인

다음 단계¶

설치가 완료되었습니다! 이제:

문제 해결¶

포트 충돌¶

다른 프로세스가 포트를 사용 중인 경우:

# 포트 사용 확인 (Linux/macOS)
lsof -i :8080
lsof -i :5173

# 프로세스 종료
kill -9 <PID>

데이터베이스 마이그레이션 오류¶

cd backend
rm -rf data/sqlite.db
cargo run

Docker 빌드 오류¶

# 캐시 없이 다시 빌드
docker compose build --no-cache

# Docker 시스템 정리
docker system prune -a

더 많은 문제 해결은 FAQ를 참조하세요.

설치 가이드¶

시스템 요구사항¶

최소 요구사항¶

소프트웨어 요구사항¶

CLI (oc) 설치¶

소스에서 설치¶

로컬 release 바이너리 빌드¶

CLI만으로 로컬 스택 실행¶

실행 후 첫 연결¶

CLI (oc) 삭제와 정리¶

1. oc run으로 띄운 로컬 스택 중지 및 데이터 정리¶

2. Cargo로 설치한 CLI 삭제¶

3. 수동으로 복사한 바이너리 삭제¶

4. 설정, 세션, 런타임 파일 정리¶

5. 제거 후 확인¶

Docker로 설치하기¶

1. Docker 설치¶

2. 프로젝트 클론¶

3. 환경 변수 설정 (선택사항)¶

4. 실행¶

5. 로그 확인¶

6. 중지 및 시작¶

Podman으로 설치하기¶

1. Podman 설치¶

2. 실행¶

로컬 개발 환경 설치¶

1. Rust 설치¶

2. Bun 설치¶

3. SQLite 설치¶

4. 프로젝트 클론 및 설정¶

5. Backend 설정¶

6. Frontend 설정¶

프로덕션 빌드¶

Docker 프로덕션 이미지¶

로컬 프로덕션 빌드¶

Backend¶

Frontend¶

SQLx CLI 설치 (개발자용)¶

데이터베이스 초기화¶

환경 변수 전체 목록¶

Backend¶

Frontend¶

검증¶

1. Health Check¶

2. Frontend 접속¶

3. 관리자 로그인¶

다음 단계¶

문제 해결¶

포트 충돌¶

데이터베이스 마이그레이션 오류¶

Docker 빌드 오류¶

CLI (`oc`) 설치¶

CLI (`oc`) 삭제와 정리¶

1. `oc run`으로 띄운 로컬 스택 중지 및 데이터 정리¶