자체 호스팅

이 문서는 logi 서버를 직접 운영하시는 분 을 위한 가이드입니다. 단순히 OAuth 통합만 하시려면 Quickstart 의 관리형 IdP(https://1pass.dev) 경로가 훨씬 빠릅니다.

언제 자체 호스팅이 필요한가

• Contributor: logi 서버 코드를 수정·기여하시는 경우
• Enterprise: 사내 사용자만을 대상으로 IdP 를 격리 운영하셔야 하는 경우
• 컴플라이언스: 사용자 데이터가 자사 인프라(예: 국내 IDC, on-prem) 를 벗어나면 안 되는 경우
• 로컬 통합 테스트: 관리형 IdP 의 sandbox 만으로 부족한 reproducible 시나리오 (예: 시간 조작, DB 직접 검증)

대부분의 RP 통합에서는 관리형 IdP 의 sandbox tier 로 충분합니다.

요구사항

항목	버전
Ruby	3.3+
Rails	8.0+
PostgreSQL	16+
Redis	7+ (SolidQueue·rate limit 백엔드용)
Node.js	20+ (JS asset 빌드용)

필수 환경 변수:

SECRET_KEY_BASE=<rails secret 결과>
DATABASE_URL=postgres://localhost/logi_development
RAILS_ENV=development

# OAuth provider (Sign in with Apple / Google) — 선택, 없으면 이메일 로그인만
APPLE_TEAM_ID=...
APPLE_KEY_ID=...
APPLE_PRIVATE_KEY="-----BEGIN PRIVATE KEY-----\n...\n-----END PRIVATE KEY-----"
APPLE_DEFAULT_CLIENT_ID=com.example.app

GOOGLE_OAUTH_CLIENT_ID=...
GOOGLE_OAUTH_CLIENT_SECRET=...

# APNs (모바일 푸시 승인 — 선택)
APNS_KEY_ID=...
APNS_TEAM_ID=...
APNS_KEY_PATH=/path/to/AuthKey_XXXXX.p8
APNS_TOPIC=com.example.app
APNS_TOPIC_MACOS=com.example.app.mac      # macOS 앱이 별도 bundle 인 경우
APNS_ENV=development

# OIDC discovery (production 에서 self-hosted 의 issuer URL)
OIDC_ISSUER=https://idp.example.com
APP_HOST=idp.example.com                  # Rails default_url_options 의 :host
LOGI_API_HOST=api.example.com             # 호스트 분리 시 — quickstart/registering-apps 호스트 게이트
LOGI_ADMIN_API_HOST=admin.example.com     # admin route 게이트 (선택)

# WebAuthn (Passkey)
WEBAUTHN_ORIGIN=https://idp.example.com
WEBAUTHN_RP_ID=example.com

# Android App Links (assetlinks.json) — 모바일 앱 운영 시
ANDROID_APP_CERT_SHA256=AB:CD:...

# 운영 토글 (production 권장)
ENFORCE_CANONICAL_RESOLUTION=true         # merge 후 canonical_sub 강제 (자세한 건 account-merge 가이드)
SOLID_QUEUE_IN_PUMA=true                  # 별도 worker 프로세스 없이 puma 안에서 SolidQueue 실행
JOB_CONCURRENCY=1                         # SolidQueue concurrency
LOGI_BETA_AUTO_APPROVE=false              # public client 베타 자동 승인 (베타 기간 한정)

# 외부 SaaS — 사용 기능에 따라 선택
RESEND_API_KEY=re_...                     # 이메일 발송
TELEGRAM_ADMIN_BOT_TOKEN=...              # production 승급 알림
TELEGRAM_ADMIN_CHAT_ID=...
FCM_PROJECT_ID=...                        # Android 푸시
FCM_SERVICE_ACCOUNT_JSON_PATH=/path/to/sa.json

Production 호스트 분리

관리형 IdP (https://1pass.dev) 는 OAuth/OIDC 엔드포인트는 api.1pass.dev 로, 콘솔 / 개발자 포털은 start.1pass.dev 로 분리되어 있습니다. self-hosted production 도 동일한 호스트 분리를 원하시면 LOGI_API_HOST + console host 환경 변수를 분리해 셋업하시고, 단일 호스트로 운영하시려면 모두 같은 도메인으로 두면 host_constraint 가 단순 통과합니다 (development/test 환경에서는 자동으로 단일 호스트로 동작).

셋업

git clone https://github.com/Dcode-Labs/logi.git
cd logi
bundle install
bin/rails db:setup
bin/rails server

서버는 http://localhost:3000 에서 동작합니다. 별도 worker 프로세스는 SolidQueue 가 puma 안에서 처리하므로 개발 환경에서는 불필요합니다.

첫 OAuth 앱 등록 (로컬)

자체 호스팅 환경에서는 quickstart 의 모든 명령이 $LOGI=http://localhost:3000 기준으로 동작합니다.

1) 개발자 계정 생성 + 로그인

export LOGI="http://localhost:3000"

curl -s -c /tmp/cookies.txt -X POST "$LOGI/developer/signup" \
  -H 'Content-Type: application/json' \
  -d '{"user": {"email_address": "dev@example.com", "password": "correctHorseBatteryStaple"}}'

2) Personal API Key 발급

/api/v1/applications 는 PAK(Personal API Key) Bearer 인증을 씁니다. 세션 쿠키로 PAK 한 번 발급:

curl -s -b /tmp/cookies.txt -X POST "$LOGI/api/v1/me/api_keys" \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "Quickstart CLI",
    "scopes": ["apps:manage", "apps:read"]
  }' | tee /tmp/pak.json

PAK=$(python3 -c 'import json; print(json.load(open("/tmp/pak.json"))["plaintext"])')

3) OAuth 앱 등록

curl -s -X POST "$LOGI/api/v1/applications" \
  -H "Authorization: Bearer $PAK" \
  -H 'Content-Type: application/json' \
  -d '{
    "application": {
      "name": "My Local App",
      "redirect_uris": ["http://localhost:4000/auth/callback"],
      "allowed_scopes": ["profile", "email"]
    }
  }' | tee /tmp/app.json

CLIENT_ID=$(python3 -c 'import json; print(json.load(open("/tmp/app.json"))["client_id"])')
CLIENT_SECRET=$(python3 -c 'import json; print(json.load(open("/tmp/app.json"))["client_secret"])')

웹 포털(http://localhost:3000/developer/applications/new) 에서 폼으로 만드셔도 됩니다.

4) 테스트용 최종 사용자 가입

curl -s -c /tmp/user-cookies.txt -X POST "$LOGI/signup" \
  -H 'Content-Type: application/json' \
  -d '{"user": {"email_address": "user@example.com", "password": "correctHorseBatteryStaple", "device_uuid": "demo-device-1"}}'

이후 Quickstart 의 4–7 단계 (PKCE → authorize → token → userinfo) 를 그대로 따라가시되, 환경 변수를 자체 호스팅 값으로 맞춰주세요:

export LOGI="http://localhost:3000"
export CLIENT_ID="logi_..."        # 위 3) 단계에서 받은 값
export CLIENT_SECRET="..."         # 위 3) 단계에서 받은 값
export REDIRECT="http://localhost:4000/auth/callback"

운영 고려사항

자체 운영 시 추가로 살피셔야 할 항목:

• Webhook 서명 키 회전 — 키 만료·교체 주기
• Threat Model — Account Merge — 머지 공격면
• Rate Limits — Redis 기반 제한 정책
• Refresh Token 정책 — Apple/Google rotation 처리

도움 필요할 때

설치 이슈는 GitHub Issues, 운영 관련 협의는 관리자 문의(FAB) 채널로 부탁드립니다.