세션 데이터가 어디에 저장되고 릴레이가 어떻게 설정되는지 직접 관리하고 싶다면, 나만의 릴레이를 운영할 수 있습니다. 클라우드 릴레이로도 충분하지만, 셀프 호스팅하면 모든 것을 직접 소유할 수 있습니다.

이 가이드는 개인 Happier 릴레이를 운영하는 방법을 다룹니다.

요약

Docker (권장 시작 방법):

docker pull happierdev/relay-server:stable
docker run -d \
  -p 3600:3600 \
  -e HANDY_MASTER_SECRET="$(openssl rand -hex 32)" \
  -e NODE_ENV=production \
  --name happier-relay \
  happierdev/relay-server:stable

또는 관리형 설치:

happier relay host install --mode system

그런 다음 클라이언트가 기본값 대신 내 릴레이 URL을 사용하도록 설정합니다.

문제

클라우드 릴레이를 사용하면:

• 세션 데이터가 내가 관리하지 않는 인프라를 거칩니다
• 데이터 보관 위치나 보존 정책을 관리할 수 없습니다
• 클라우드 서비스의 가용성에 의존합니다
• 속도 제한과 정책을 맞춤 설정하기 어렵습니다

워크플로에 따라서는 이걸로 충분합니다. 그렇지 않다면 다음이 필요합니다.

• 인프라를 완전히 소유하기
• 데이터를 내 네트워크나 선택한 호스팅 안에 두기
• 맞춤 인증과 접근 정책
• 업데이트와 설정 관리

흔한 방법과 트레이드오프

• 클라우드 릴레이: 잘 동작하지만, 데이터가 내 인프라에 있지 않습니다.
• 소스에서 빌드: 가능하지만 의존성과 빌드 단계를 계속 따라가야 합니다.
• 자체 릴레이 구현: 유지 보수 부담이 됩니다.

공식 릴레이 셀프 호스팅으로 이 문제를 해결할 수 있습니다.

• 미리 빌드된 Docker 이미지
• 관리형 설치 옵션
• 클라우드 버전과 같은 릴레이 프로토콜
• 배포를 완전히 관리

Happier가 처음이라면

Happier는 Claude Code, Codex, OpenCode 같은 AI 코딩 에이전트를 위한 오픈 소스 컴패니언 앱입니다.

릴레이는 서버 구성 요소로, 다음을 담당합니다.

• 기기 간 메시지 전달
• 세션 메타데이터 저장
• 인증 처리
• 종단 간 암호화된 메시지 전달

릴레이를 셀프 호스팅하면 세션과 승인이 내 인프라 밖으로 나가지 않습니다.

설정 시작하기:

• GitHub: https://github.com/happier-dev/happier
• 셀프 호스팅 문서: https://docs.happier.dev/self-hosting
• Discord: https://discord.gg/W6Pb8KuHfg

사전 준비

배포 방법을 하나 고릅니다.

Docker (권장)

• Docker 설치
• 공인 IP가 있거나 사설 네트워크로 접근 가능한 호스트
• 사용 가능한 3600 포트 (또는 다른 포트 설정)

관리형 설치

• Linux 또는 macOS 머신
• Happier CLI 설치
• 서비스 실행 가능 (systemd 또는 사용자 서비스)

러너 (고급)

• Node.js 또는 Bun
• 프로세스 관리자 (PM2, systemd 등)
• 아티팩트 수동 관리

방법 1: Docker (대부분에게 권장)

Docker를 쓰면 적은 설정으로 빠르게 셀프 호스팅을 시작할 수 있습니다.

1) 이미지 받기

docker pull happierdev/relay-server:stable

사용 가능한 태그:

• stable: 프로덕션 릴리스
• preview: 프리뷰 릴리스
• dev: 개발 빌드

프로덕션에서는 stable을 사용하세요.

2) 마스터 시크릿 생성

마스터 시크릿은 저장 데이터를 암호화하고 인증 토큰을 파생하는 데 쓰입니다.

openssl rand -hex 32

이 값을 안전하게 보관하세요. 잃어버리지 마세요: 시크릿을 바꾸면 기존 데이터를 읽을 수 없게 됩니다.

3) 컨테이너 실행

docker run -d \
  -p 3600:3600 \
  -e HANDY_MASTER_SECRET="your-secret-from-step-2" \
  -e NODE_ENV=production \
  --name happier-relay \
  --restart unless-stopped \
  happierdev/relay-server:stable

4) 실행 중인지 확인

docker logs happier-relay

다음과 같이 보여야 합니다.

[info] Happier relay server starting...
[info] Listening on http://0.0.0.0:3600

5) 클라이언트가 내 릴레이를 쓰도록 설정

Happier 앱에서:

1. Settings → Server로 이동
2. 새 서버 프로필 추가
3. 릴레이 URL 입력: http://your-server-ip:3600
4. 저장하고 연결

Happier CLI에서:

happier config set relay.url http://your-server-ip:3600

클라이언트 설정에 대한 자세한 내용은 셀프 호스팅 빠른 시작을 참고하세요.

방법 2: 관리형 설치 (서비스 기반 배포)

관리형 설치는 부팅 시 시작되고 업데이트 명령도 제공하는 시스템 서비스를 만듭니다.

1) Happier CLI 설치

CLI 설치 가이드를 따르세요.

2) 릴레이를 시스템 서비스로 설치

happier relay host install --mode system

사용자 모드로 설치하려면 (sudo 불필요):

happier relay host install --mode user

3) 마스터 시크릿 설정

서비스 설정을 편집합니다.

sudo nano /etc/happier-relay/env

다음을 추가합니다.

HANDY_MASTER_SECRET=your-secret-here
NODE_ENV=production

4) 릴레이 시작

happier relay host start

5) 상태 확인

happier relay host status

다음과 같이 보여야 합니다.

Relay service: active (running)

6) 클라이언트 설정

Docker 방법과 같습니다. 클라이언트 설정에 릴레이 URL을 추가하세요.

방법 3: 러너 (고급 사용자용)

러너는 시작할 때 릴레이 아티팩트를 가져와 검증한 뒤 서버 바이너리를 실행합니다.

다음과 같은 환경에 적합합니다.

• 이미 프로세스 관리자를 쓰고 있음
• 재시작할 때 아티팩트를 내려받고 싶음
• Docker나 서비스 관리를 쓰고 싶지 않음

1) 릴레이 서버 패키지 실행

npx --yes --package @happier-dev/relay-server happier-server \
  --master-secret "your-secret-here" \
  --port 3600

2) 프로세스 관리자와 함께 사용

PM2 예시:

pm2 start npx --name happier-relay -- \
  --yes --package @happier-dev/relay-server happier-server \
  --master-secret "your-secret-here" \
  --port 3600
pm2 save

러너에 대한 자세한 내용은 셀프 호스팅 런타임 문서를 참고하세요.

환경 변수 설정

주요 환경 변수:

전체 목록은 환경 변수 문서를 참고하세요.

인증 설정

기본적으로 릴레이는 비밀번호 기반 인증을 사용합니다.

프로덕션에서는 다음을 고려하세요.

• GitHub OAuth: GitHub 인증 참고
• OIDC: OIDC 인증 참고
• mTLS: mTLS 인증 참고

HTTPS와 리버스 프록시

프로덕션에서는 릴레이를 HTTPS를 지원하는 리버스 프록시 뒤에 두세요.

nginx 예시:

server {
    listen 443 ssl;
    server_name relay.example.com;

    ssl_certificate /path/to/cert.pem;
    ssl_certificate_key /path/to/key.pem;

    location / {
        proxy_pass http://localhost:3600;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
    }
}

그러면 클라이언트는 https://relay.example.com에 연결합니다.

업데이트

Docker

docker pull happierdev/relay-server:stable
docker stop happier-relay
docker rm happier-relay
# Re-run the docker run command with the new image

관리형 설치

happier relay host install --mode system
happier relay host restart

러너

러너는 재시작할 때 새 아티팩트를 자동으로 가져옵니다.

문제 해결

증상: 컨테이너가 바로 종료됨

가능한 원인:

• HANDY_MASTER_SECRET이 없거나 유효하지 않음
• 포트가 이미 사용 중

해결:

1. 컨테이너 로그 확인: docker logs happier-relay
2. 환경 변수가 설정되어 있는지 확인
3. 포트 사용 여부 확인: lsof -i :3600

증상: 클라이언트가 연결되지 않음

가능한 원인:

• 방화벽이 3600 포트를 막고 있음
• 릴레이가 올바른 인터페이스에서 수신하지 않음
• 클라이언트의 릴레이 URL이 잘못됨

해결:

1. 릴레이가 실행 중인지 확인: docker ps 또는 happier relay host status
2. 방화벽 확인: sudo ufw allow 3600/tcp
3. 연결 테스트: curl http://your-server-ip:3600
4. 클라이언트의 릴레이 URL이 서버 주소와 일치하는지 확인

증상: "Authentication failed" 오류

가능한 원인:

• 릴레이와 클라이언트 등록 사이에 마스터 시크릿이 바뀜
• 인증 토큰을 유지하지 않고 릴레이를 재시작함

해결:

1. HANDY_MASTER_SECRET이 일관된지 확인
2. 마스터 시크릿이 바뀌었다면 클라이언트를 다시 등록
3. 릴레이 로그에서 인증 오류 확인

증상: 업데이트가 적용되지 않음

Docker:

• 컨테이너를 다시 만들기 전에 이미지를 받았는지 확인
• 이미지 태그가 바뀌지 않았는지 확인

관리형 설치:

• happier relay host install을 다시 실행
• 설치 후 서비스를 재시작

자주 묻는 질문

꼭 셀프 호스팅해야 하나요?

아니요. 대부분의 사용자에게는 클라우드 릴레이로 충분합니다.

다음과 같은 경우 셀프 호스팅하세요.

• 데이터 보관 위치를 보장해야 함
• 인프라를 완전히 관리하고 싶음
• 규정 준수 요구 사항이 있음
• 직접 관리하는 서비스를 선호함

클라우드에서 셀프 호스팅으로 옮길 수 있나요?

네, 하지만 세션이 자동으로 옮겨지지는 않습니다.

절차:

1. 셀프 호스팅 릴레이 준비
2. 클라이언트가 새 릴레이 URL을 쓰도록 설정
3. 기존 클라우드 세션은 클라우드 릴레이에 남음
4. 새 세션은 셀프 호스팅 릴레이를 사용

종단 간 암호화는 계속 유지되나요?

네. E2E 암호화는 클라이언트 측에서 이루어지며 어떤 릴레이를 쓰든 상관없습니다.

릴레이 운영자(본인이든 클라우드 제공자든)는 어느 경우에도 세션 내용을 읽을 수 없습니다.

릴레이 데이터는 어떻게 백업하나요?

릴레이는 데이터 디렉터리에 데이터를 저장합니다.

Docker: 볼륨 마운트를 추가합니다.

-v /path/to/data:/data

관리형 설치: 데이터 위치는 OS마다 다릅니다. happier relay host status로 확인하세요.

백업:

1. 릴레이 중지
2. 데이터 디렉터리 복사
3. 릴레이 재시작

릴레이 인스턴스를 여러 개 실행할 수 있나요?

네, 고가용성이나 부하 분산을 위해 가능합니다.

요구 사항:

• 공유 데이터 저장소 (데이터베이스)
• 앞단의 로드 밸런서
• 모든 인스턴스에서 같은 HANDY_MASTER_SECRET

클러스터 설정은 환경 변수 문서를 참고하세요.

관련 가이드

• 휴대폰에서 Happier 사용하는 방법
• Happier와 Claude Code Remote Control 비교