설치 가이드 - SessionCast

개요

⚠️ 보안 면책 조항

SessionCast는 어떠한 보증 없이 "있는 그대로" 제공됩니다. 본 소프트웨어를 사용함으로써 다음에 동의하는 것으로 간주됩니다:

배포 및 데이터의 보안에 대한 책임은 전적으로 사용자에게 있습니다
개발자는 보안 침해, 데이터 손실 또는 손해에 대해 어떠한 책임도 지지 않습니다
터미널 세션에는 민감한 정보가 포함될 수 있으므로 적절한 접근 제어를 사용하세요
자체 호스팅 배포 시 적절한 보안 설정이 필요합니다 (HTTPS, 방화벽, 인증)

전체 약관은 MIT 라이선스를 참조하세요.

SessionCast는 세 가지 주요 컴포넌트로 구성됩니다:

릴레이 서버

에이전트와 웹 클라이언트 사이의 WebSocket 통신을 중계하고 인증을 관리합니다.

웹 클라이언트

브라우저에서 터미널 세션을 보고 상호작용할 수 있는 React 기반 웹 애플리케이션입니다.

에이전트

로컬 머신에서 실행되어 tmux 세션을 캡처하고 릴레이 서버로 스트리밍합니다.

배포 방식 선택

로컬 배포 (내부용)

로컬 네트워크에서 개인 또는 내부 팀 용도로 SessionCast를 실행합니다. 테스트, 개발, 또는 홈 오피스 환경에 적합합니다.

사전 요구사항

Java 17 이상
Node.js 18 이상 (웹 클라이언트 빌드용)
Docker (권장) 또는 로컬 환경
Google Cloud Console의 OAuth 2.0 클라이언트 ID

Docker로 빠른 시작

Docker Compose

# 저장소 클론
git clone https://github.com/sessioncast/server.git
cd server

# .env 파일 생성
cat > .env << EOF
GOOGLE_CLIENT_ID=your-client-id
GOOGLE_CLIENT_SECRET=your-client-secret
JWT_SECRET=your-jwt-secret-key-at-least-256-bits
FRONTEND_URL=http://localhost:3000
CORS_ORIGINS=http://localhost:3000
EOF

# Docker Compose로 실행
docker-compose up -d

수동 설치

1. 릴레이 서버

Bash

# 클론 및 빌드
git clone https://github.com/sessioncast/server.git
cd server
./gradlew build -x test

# 실행
java -jar build/libs/relay-0.0.1-SNAPSHOT.jar

2. 웹 클라이언트

Bash

# 클론 및 빌드
git clone https://github.com/sessioncast/web.git
cd web
npm install

# 설정
echo "VITE_API_URL=http://localhost:8080" > .env
echo "VITE_WS_URL=ws://localhost:8080/ws" >> .env

# 개발 서버 실행
npm run dev

Google OAuth 설정

Google Cloud Console로 이동
OAuth 2.0 클라이언트 ID 생성 (웹 애플리케이션 유형)
승인된 리디렉션 URI 추가: http://localhost:8080/login/oauth2/code/google
클라이언트 ID와 시크릿을 환경 변수에 복사

AWS 배포 (프로덕션)

안정적이고 확장 가능한 프로덕션 환경을 위해 AWS에 SessionCast를 배포합니다. HTTPS, 로드 밸런싱, 오토 스케일링을 포함합니다.

사전 요구사항

적절한 권한을 가진 AWS 계정
AWS CLI 구성됨
도메인 이름 (SSL 인증서용)
Google Cloud Console의 OAuth 2.0 클라이언트 ID

아키텍처 개요

AWS 아키텍처

┌─────────────────────────────────────────────────────────┐
│                      Route 53                           │
│                    (DNS + SSL)                          │
└─────────────────────┬───────────────────────────────────┘
                      │
┌─────────────────────▼───────────────────────────────────┐
│              Application Load Balancer                   │
│                   (HTTPS:443)                            │
└─────────────────────┬───────────────────────────────────┘
                      │
        ┌─────────────┴─────────────┐
        │                           │
┌───────▼───────┐           ┌───────▼───────┐
│   ECS Fargate │           │   S3 + CF     │
│  (릴레이 서버) │           │ (웹 클라이언트)│
└───────────────┘           └───────────────┘

1단계: ECR 저장소 생성

AWS CLI

# ECR 저장소 생성
aws ecr create-repository --repository-name sessioncast-server

# ECR 로그인
aws ecr get-login-password --region us-east-1 | \
  docker login --username AWS --password-stdin \
  YOUR_ACCOUNT_ID.dkr.ecr.us-east-1.amazonaws.com

# 빌드 및 푸시
docker build -t sessioncast-server .
docker tag sessioncast-server:latest \
  YOUR_ACCOUNT_ID.dkr.ecr.us-east-1.amazonaws.com/sessioncast-server:latest
docker push YOUR_ACCOUNT_ID.dkr.ecr.us-east-1.amazonaws.com/sessioncast-server:latest

2단계: ECS 클러스터 생성

AWS CLI

# 클러스터 생성
aws ecs create-cluster --cluster-name sessioncast-cluster

# 태스크 정의 생성 (task-definition.json으로 저장)
{
  "family": "sessioncast-server",
  "networkMode": "awsvpc",
  "requiresCompatibilities": ["FARGATE"],
  "cpu": "512",
  "memory": "1024",
  "containerDefinitions": [
    {
      "name": "server",
      "image": "YOUR_ACCOUNT_ID.dkr.ecr.us-east-1.amazonaws.com/sessioncast-server:latest",
      "portMappings": [{"containerPort": 8080}],
      "environment": [
        {"name": "GOOGLE_CLIENT_ID", "value": "your-client-id"},
        {"name": "GOOGLE_CLIENT_SECRET", "value": "your-secret"},
        {"name": "JWT_SECRET", "value": "your-jwt-secret"},
        {"name": "FRONTEND_URL", "value": "https://your-domain.com"}
      ]
    }
  ]
}

# 태스크 등록
aws ecs register-task-definition --cli-input-json file://task-definition.json

3단계: S3 + CloudFront에 웹 클라이언트 배포

AWS CLI

# S3 버킷 생성
aws s3 mb s3://sessioncast-web-client

# 웹 클라이언트 빌드
cd web
npm run build

# S3에 업로드
aws s3 sync dist/ s3://sessioncast-web-client --delete

# CloudFront 배포 생성 (AWS 콘솔 또는 CLI 사용)
# 보안을 위해 OAI와 함께 S3 버킷을 연결

4단계: ACM으로 SSL 설정

AWS CLI

# 인증서 요청 (CloudFront용으로 us-east-1에서 요청 필요)
aws acm request-certificate \
  --domain-name your-domain.com \
  --validation-method DNS \
  --region us-east-1

# Route 53 DNS 레코드로 검증

보안 모범 사례

시크릿은 AWS Secrets Manager에 저장
최소 권한의 IAM 역할 사용
ECS 태스크에 VPC 활성화
추가 보호를 위해 WAF 구성

🚀 SessionCast Cloud (베타)

가장 쉬운 시작 방법! 서버 설정 없이 CLI 설치 후 브라우저로 로그인하면 터미널 세션 스트리밍을 바로 시작할 수 있습니다.

1단계: CLI 설치

Bash

# SessionCast CLI를 전역으로 설치
npm install -g sessioncast-cli

2단계: 로그인 (브라우저 기반)

Google 계정으로 로그인 - 브라우저가 자동으로 열립니다:

Bash

# 브라우저가 열리며 인증 진행
sessioncast login

# ✓ You are now logged in to SessionCast

3단계: Agent 실행

Bash

# 에이전트 시작
sessioncast agent

# 브라우저에서 접속:
# https://app.sessioncast.io

✨ 끝!

tmux 세션이 웹 콘솔에 자동으로 표시됩니다. 수동 토큰 설정이 필요 없습니다!

선택사항: 상태 확인

Bash

# 로그인 상태 확인
sessioncast status

# 필요시 로그아웃
sessioncast logout

✨ Free 플랜 포함

Free 플랜으로 시작하세요 - 1개 에이전트 연결과 기본 기능이 포함됩니다. 더 많은 에이전트와 고급 기능을 위해 언제든지 업그레이드하세요.

에이전트 설정

에이전트는 로컬 머신에서 실행되어 tmux 세션을 서버로 스트리밍합니다.

사전 요구사항

Node.js 18 이상
tmux 설치됨 (Linux/macOS) 또는 itmux (Windows)
Linux, macOS, 또는 Windows

에이전트 설치

Bash

# SessionCast CLI를 전역으로 설치
npm install -g sessioncast-cli

로그인 (SaaS 권장)

SessionCast Cloud 사용 시 브라우저 기반 로그인 - 수동 토큰 설정 불필요:

Bash

# 브라우저로 로그인 (자동으로 열림)
sessioncast login

# 로그인 상태 확인
sessioncast status

수동 설정 (자체 호스팅)

자체 호스팅 배포 시 ~/.sessioncast.yml 파일을 생성하세요:

~/.sessioncast.yml

# 머신 식별자 (머신당 고유)
machineId: my-workstation

# 릴레이 서버 WebSocket URL
relay: wss://your-server.com/ws   # 로컬의 경우 ws://localhost:8080/ws

# 에이전트 인증 토큰
token: agt_your_secure_token_here

보안 주의

에이전트 토큰은 민감한 정보입니다. 공개 저장소에 절대 커밋하지 마세요.

에이전트 실행

Bash

# 직접 실행
sessioncast agent

# 또는 백그라운드에서 실행
nohup sessioncast agent > ~/sessioncast-agent.log 2>&1 &

macOS 자동 시작 (launchd)

~/Library/LaunchAgents/com.sessioncast.agent.plist

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN"
  "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
    <key>Label</key>
    <string>com.sessioncast.agent</string>
    <key>ProgramArguments</key>
    <array>
        <string>/usr/local/bin/sessioncast</string>
        <string>agent</string>
    </array>
    <key>RunAtLoad</key>
    <true/>
    <key>KeepAlive</key>
    <true/>
    <key>EnvironmentVariables</key>
    <dict>
        <key>PATH</key>
        <string>/usr/local/bin:/usr/bin:/bin</string>
    </dict>
</dict>
</plist>

서비스 로드

launchctl load ~/Library/LaunchAgents/com.sessioncast.agent.plist

Windows 설정 (itmux 사용)

Windows에는 네이티브 tmux가 없습니다. SessionCast는 Windows 호환성을 위해 itmux (Cygwin + tmux 번들)를 사용합니다.

1단계: itmux 설치

PowerShell

# 옵션 1: GitHub에서 다운로드
# https://github.com/phayte/itmux/releases
# C:\itmux에 압축 해제

# 옵션 2: Chocolatey 사용
choco install itmux

# 옵션 3: Scoop 사용
scoop install itmux

2단계: 환경 변수 설정

PowerShell (관리자)

# ITMUX_HOME 환경 변수 설정
[Environment]::SetEnvironmentVariable("ITMUX_HOME", "C:\itmux", "User")

# 설치 확인
$env:ITMUX_HOME = "C:\itmux"
& "$env:ITMUX_HOME\bin\bash.exe" -c "tmux -V"

3단계: SessionCast 설치 및 실행

PowerShell

# SessionCast CLI 설치
npm install -g sessioncast-cli

# 로그인
sessioncast login

# 에이전트 시작 (itmux 자동 사용)
sessioncast agent

Windows 경로 자동 감지

SessionCast는 다음 위치에서 itmux를 자동으로 검색합니다:

ITMUX_HOME 환경 변수
%USERPROFILE%\itmux
C:\itmux
C:\Program Files\itmux

설정 레퍼런스

릴레이 서버 환경 변수

변수	설명	기본값
`GOOGLE_CLIENT_ID`	Google OAuth 2.0 클라이언트 ID	필수
`GOOGLE_CLIENT_SECRET`	Google OAuth 2.0 클라이언트 시크릿	필수
`JWT_SECRET`	JWT 서명 키 (최소 256 bits)	필수
`FRONTEND_URL`	웹 클라이언트 URL	http://localhost:3000
`CORS_ORIGINS`	허용된 CORS origins (쉼표 구분)	http://localhost:3000
`ALLOWED_DOMAINS`	허용된 이메일 도메인 (쉼표 구분)	모든 도메인 허용

에이전트 설정 (YAML)

속성	설명	필수 여부
`machineId`	고유한 머신 식별자	예
`relay`	릴레이 서버 WebSocket URL	예
`token`	에이전트 인증 토큰	예
`autoDiscovery`	tmux 세션 자동 감지	아니오 (기본값: false)
`sessions`	수동 세션 설정 목록	아니오