콘텐츠로 이동

공개 배포 (ngrok/bore/cloudflare)

로컬 서버를 외부에 공개하여 워크샵이나 행사에서 사용하는 방법입니다.

개요

Open Codelabs는 run-public.sh 스크립트를 제공하여 로컬 서버를 쉽게 공개할 수 있습니다:

  • ngrok: 가장 인기 있는 터널링 서비스
  • bore: Rust 기반 오픈소스 대안
  • Cloudflare Tunnel: 무료 quick tunnel 제공 (cloudflared)

ngrok 사용하기

1. ngrok 설치

brew install ngrok

# Snap
snap install ngrok

# 또는 직접 다운로드
wget https://bin.equinox.io/c/bNyj1mQVY4c/ngrok-v3-stable-linux-amd64.tgz
tar xvzf ngrok-v3-stable-linux-amd64.tgz
sudo mv ngrok /usr/local/bin

ngrok 다운로드 페이지에서 설치

2. ngrok 인증 (선택사항)

무료 플랜에서도 사용 가능하지만, 계정 등록 시 더 많은 기능 사용 가능:

# ngrok.com에서 가입 후 토큰 복사
ngrok config add-authtoken <your_token>

3. 실행

chmod +x run-public.sh
./run-public.sh --ngrok

출력 예시:

🚀 Starting Open-Codelabs: Hands-on System using docker...
✅ Containers are up!
🌐 Starting ngrok tunnel on port 5173...
------------------------------------------------
🎉 Your Codelab is now PUBLIC!
Admin Dashboard: https://abc123.ngrok-free.app/admin
Attendee Entry:  https://abc123.ngrok-free.app
------------------------------------------------

4. QR 코드 생성

참가자가 쉽게 접속할 수 있도록 QR 코드 생성:

# qrencode 설치
brew install qrencode  # macOS
apt-get install qrencode  # Linux

# QR 코드 생성
echo "https://abc123.ngrok-free.app" | qrencode -t UTF8

# 또는 이미지로 저장
echo "https://abc123.ngrok-free.app" | qrencode -o qr.png

관리자 대시보드에도 자동으로 QR 코드가 표시됩니다!

bore 사용하기

bore는 오픈소스 대안으로, 자체 서버에서 운영 가능합니다.

1. bore 설치

cargo install bore-cli

2. 실행

./run-public.sh --bore

bore는 기본적으로 bore.pub 서버를 사용합니다.

3. 커스텀 bore 서버

자체 bore 서버 운영:

# 서버 실행
bore server --secret <your_secret>

# 클라이언트 연결
bore local 5173 --to your-server.com --port 80 --secret <your_secret>

Cloudflare Tunnel 사용하기

Cloudflare Tunnel은 무료 quick tunnel을 제공하며, trycloudflare.com URL이 자동으로 생성됩니다.

1. cloudflared 설치

brew install cloudflare/cloudflare/cloudflared

Cloudflare 다운로드 안내에서 설치

Cloudflare 다운로드 안내에서 설치

2. 실행

./run-public.sh --cloudflare

cloudflared 실행 로그에 공개 URL이 표시됩니다.

run-public.sh 스크립트 상세

스크립트 내용

#!/bin/bash

set -e

# Default values
TUNNEL_TYPE="ngrok"
CONTAINER_ENGINE="docker"
PORT="${PORT:-5173}"

# Check for podman
if command -v podman-compose &> /dev/null; then
    CONTAINER_ENGINE="podman"
elif command -v docker-compose &> /dev/null; then
    CONTAINER_ENGINE="docker"
else
    echo "❌ No container engine found!"
    exit 1
fi

# Parse arguments
while [[ "$#" -gt 0 ]]; do
    case $1 in
        --bore) TUNNEL_TYPE="bore"; shift ;;
        --cloudflare) TUNNEL_TYPE="cloudflare"; shift ;;
        --ngrok) TUNNEL_TYPE="ngrok"; shift ;;
        *) echo "Unknown parameter: $1"; exit 1 ;;
    esac
done

echo "🚀 Starting Open-Codelabs Hands-on System using $CONTAINER_ENGINE..."

# Start containers in background
if [ "$CONTAINER_ENGINE" == "podman" ]; then
    podman-compose up -d
else
    docker-compose up -d
fi

echo "✅ Containers are up!"

if [ "$TUNNEL_TYPE" == "ngrok" ]; then
    echo "🌐 Starting ngrok tunnel on port $PORT..."
    ngrok http "$PORT" --log=stdout &
    sleep 5
    PUBLIC_URL=$(curl -s http://localhost:4040/api/tunnels | grep -o 'https://[^"]*.ngrok-free.app' | head -n 1)
elif [ "$TUNNEL_TYPE" == "bore" ]; then
    echo "🌐 Starting bore tunnel on port $PORT..."
    bore local "$PORT" --to bore.pub &
    sleep 5
    echo "⚠️  Please check the bore output above for your public URL."
    PUBLIC_URL="[Check Bore Output]"
elif [ "$TUNNEL_TYPE" == "cloudflare" ]; then
    echo "🌐 Starting Cloudflare tunnel on port $PORT..."
    cloudflared tunnel --url "http://localhost:$PORT" --no-autoupdate &
    sleep 5
    echo "⚠️  Please check the cloudflared output above for your public URL."
    PUBLIC_URL="[Check Cloudflared Output]"
fi

if [ -z "$PUBLIC_URL" ] || [ "$PUBLIC_URL" == "[Check Bore Output]" ] || [ "$PUBLIC_URL" == "[Check Cloudflared Output]" ]; then
    if [ "$TUNNEL_TYPE" == "ngrok" ]; then
        echo "❌ Failed to get ngrok URL. Is ngrok running?"
    fi
else
    echo "------------------------------------------------"
    echo "🎉 Your Codelab is now PUBLIC!"
    echo "Admin Dashboard: $PUBLIC_URL/admin"
    echo "Attendee Entry:  $PUBLIC_URL"
    echo "------------------------------------------------"
fi

# Keep script running
wait

커스터마이징

포트 변경:

# 스크립트 수정
ngrok http 3000  # 5173 대신 3000

# 또는 환경 변수로
PORT=3000 ./run-public.sh --ngrok

워크샵 시나리오

사전 준비 (행사 전날)

  1. 로컬 테스트
# Docker로 전체 시스템 테스트
docker-compose up

# 브라우저에서 확인
open http://localhost:5173
  1. Codelab 생성 및 검증
  2. 모든 Step 작성 완료
  3. 이미지 업로드 완료

  4. Export하여 백업

  5. 네트워크 테스트

# ngrok 터널 테스트
./run-public.sh --ngrok

# 다른 디바이스에서 접속 테스트

행사 당일

1시간 전

# 시스템 시작
./run-public.sh --ngrok

# URL 확인 및 QR 코드 준비
# 프로젝터로 QR 코드 표시

행사 시작

  1. 참가자 안내
  2. QR 코드 스캔 또는 URL 접속

  3. 이름과 참가 코드 입력

  4. 실시간 모니터링

  5. 관리자 대시보드로 진행 상황 확인

  6. 도움 요청에 즉시 응답

  7. 채팅 활용

  8. 공지사항 전달
  9. 질문 답변
  10. 1:1 지원

행사 종료

# 피드백 수집 (자동)
# 데이터 백업
docker cp $(docker-compose ps -q backend):/app/data/sqlite.db ./backup_$(date +%Y%m%d).db

# 시스템 종료
docker-compose down

보안 고려사항

ngrok 보안 설정

# Basic Auth 추가
ngrok http 5173 --basic-auth="user:password"

# IP 화이트리스트 (유료 플랜)
ngrok http 5173 --cidr-allow=192.168.1.0/24

임시 URL 사용

ngrok의 무료 플랜은 세션마다 새로운 URL 생성:

  • 장점: 행사 후 자동으로 접근 불가
  • 단점: URL 변경 시 다시 공유 필요

HTTPS

ngrok은 자동으로 HTTPS 제공:

https://abc123.ngrok-free.app  ← 자동 SSL/TLS

대안 솔루션

localtunnel

Node.js 기반 대안:

npm install -g localtunnel
lt --port 5173

Tailscale

VPN 기반 접근 (더 안전):

# Tailscale 설치 및 설정
brew install tailscale
tailscale up

# 참가자도 Tailscale 설치 필요

성능 최적화

ngrok 대역폭

무료 플랜 제한:

  • 연결 수: 40/분
  • 대역폭: 제한 없음
  • 터널 수: 1개

대규모 행사 (100명 이상):

  • ngrok Pro 플랜 권장
  • 또는 Cloudflare Tunnel 사용

네트워크 안정성

# ngrok 재연결 설정
ngrok http 5173 --log=stdout --log-level=info

백그라운드 실행:

# systemd 서비스 (Linux)
cat > /etc/systemd/system/codelabs-tunnel.service << EOF
[Unit]
Description=Codelabs ngrok Tunnel
After=network.target

[Service]
Type=simple
User=your_user
WorkingDirectory=/path/to/open-codelabs
ExecStart=/usr/local/bin/ngrok http 5173
Restart=always

[Install]
WantedBy=multi-user.target
EOF

sudo systemctl enable codelabs-tunnel
sudo systemctl start codelabs-tunnel

모니터링

ngrok 대시보드

ngrok 실행 중 http://localhost:4040에서 확인:

  • 실시간 요청/응답
  • 대역폭 사용량
  • 에러 로그

시스템 리소스

# 실시간 모니터링
docker stats

# 로그 확인
docker-compose logs -f --tail=100

문제 해결

ngrok 연결 실패

# ngrok 프로세스 확인
ps aux | grep ngrok

# 포트 사용 확인
lsof -i :4040
lsof -i :5173

# ngrok 재시작
killall ngrok
./run-public.sh --ngrok

URL을 가져올 수 없음

# ngrok API 직접 확인
curl http://localhost:4040/api/tunnels | jq .

# 수동으로 URL 확인
open http://localhost:4040

느린 연결 속도

  • 가까운 ngrok 리전 선택:
ngrok http 5173 --region=jp  # 일본
ngrok http 5173 --region=ap  # 아시아-태평양

다음 단계