자체 호스팅

Source: guide/self-hosting.md · Live: https://docs.1pass.dev/guide/self-hosting LLM-sanitized: internal links absolutized, VitePress containers → admonitions, line numbers in the Jump-to Index reference this rendered file (1-indexed).

📍 Jump-to Index

• L31-L39: ## 언제 자체 호스팅이 필요한가
• L40-L103: ## 요구사항
• L104-L123: ## 셋업
• L124-L189: ## 첫 OAuth 앱 등록 (로컬)
  • L128-L137: ### 1) 개발자 계정 생성 + 로그인
  • L138-L152: ### 2) Personal API Key 발급
  • L153-L172: ### 3) OAuth 앱 등록
  • L173-L189: ### 4) 테스트용 최종 사용자 가입
• L190-L198: ## 운영 고려사항
• L199-L202: ## 도움 필요할 때

---

자체 호스팅

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

⚠️ Warning: 알파 · 파트너 한정 자체 호스팅은 현재 알파 단계이며 파트너/컨트리뷰터에게만 공개됩니다. 소스 접근은 온보딩/파트너십 과정에서 제공됩니다 (문의: support@1pass.dev). 공개 셀프서비스 배포 패키지는 아직 제공되지 않으며, 컨테이너 이미지 · Helm 차트 등은 패키징 전입니다 (아래 셋업 참고).

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

• 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

⚠️ Warning: 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 환경에서는 자동으로 단일 호스트로 동작).

셋업

소스 접근은 온보딩/파트너십 과정에서 제공됩니다 — 문의: support@1pass.dev. 아래의 <your-logi-repo> 를 제공받은 저장소 URL 로 교체하세요.

git clone <your-logi-repo>
cd logi
bundle install
bin/rails db:setup
bin/rails server

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

💡 Tip: 컨테이너 / Helm 저장소에는 production 빌드용 server/Dockerfile 이 포함되어 있어 직접 이미지를 빌드해 운영하실 수 있습니다. 다만 공식 배포 컨테이너 이미지 레지스트리 · docker-compose · Helm 차트는 아직 패키징 전입니다 — 알파 단계 동안에는 위의 bundle install + bin/rails 직접 실행 또는 직접 빌드한 Docker 이미지를 권장합니다.

첫 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:basic", "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) 채널로 부탁드립니다.