배포 Runbook

⚠️ 운영자 전용 — RP 통합 개발자가 읽을 페이지 아닙니다. 이 문서는 logi-server / docs-site / logi-db Render 인스턴스를 직접 배포/롤백하는 운영팀을 위한 것입니다.

📌 Placeholder 표기: 이 페이지의 <LOGI_WEB_SERVICE_ID> / <LOGI_DOCS_SERVICE_ID> / <LOGI_PG_INSTANCE_ID> 는 실제 Render 리소스 ID 를 가리는 자리표시자입니다. 운영팀 internal runbook 또는 Render Dashboard → Service settings 에서 실제 값을 확인하세요. (외부에 공개되는 docs subdomain 정책 — 2026-05-15.)

서비스 인벤토리

자원	ID	autoDeploy	메모
logi-server (web)	<LOGI_WEB_SERVICE_ID>	수동	standard plan, Singapore, https://logi-server.onrender.com → api.1pass.dev
logi-docs (static)	<LOGI_DOCS_SERVICE_ID>	자동 (push main)	VitePress 빌드
logi-db (postgres)	<LOGI_PG_INSTANCE_ID>	—	basic_256mb, PG 18

(라이브 값은 Render API get_service / get_postgres 로 검증됨 — 2026-05-15.)

worker 는 없음 — SOLID_QUEUE_IN_PUMA=true 로 web 프로세스 안에서 dispatcher+worker 동작. (별도 logi-solidqueue 서비스가 prod 에 존재하지 않음을 2026-05-15 list_services 로 재확인. server/render.yaml 의 worker 항목은 같은 시점에 제거됨.)

배포 트리거

docs-site

origin/main push 즉시 Render 가 픽업 → VitePress build → publish. 별도 액션 불필요.

logi-server (수동)

Render dashboard → 서비스 → Manual Deploy → "Deploy latest commit" 클릭. 또는 API:

curl -X POST "https://api.render.com/v1/services/<LOGI_WEB_SERVICE_ID>/deploys" \
  -H "Authorization: Bearer $RENDER_API_KEY"

배포된 commit 확인:

curl -s "https://api.render.com/v1/services/<LOGI_WEB_SERVICE_ID>/deploys?limit=5" \
  -H "Authorization: Bearer $RENDER_API_KEY" | jq '.[].deploy | {id, commit: .commit.id, status, createdAt}'

사전 검증

배포 전 로컬에서:

cd server
bundle exec rubocop --parallel
bundle exec rspec
bundle exec brakeman --quiet -q -w2
bin/rails zeitwerk:check

CI (.github/workflows/ci.yml) 도 동일 체크 — green PR 만 main merge.

마이그레이션

⚠️ Render 는 자동 마이그레이션 실행하지 않음. 배포 직후 SSH 로 수동 실행:

ssh -o StrictHostKeyChecking=no \
  <LOGI_WEB_SERVICE_ID>@<RENDER_SSH_HOST> \
  "cd /opt/render/project/src/server && \
   /opt/render/project/.gems/bin/bundle exec rails db:migrate RAILS_ENV=production 2>&1"

• client_global_hostkeys_prove_confirm 경고는 무시.
• destructive 마이그레이션 (drop column 등) 은 배포 전 별도 PR + 별도 단계 — code 와 schema 가 둘 다 stale row 를 read 할 수 있게 한 사이클 묵힌 후 다음 PR 에서 제거.

사후 검증

배포 + 마이그 후 5분 이내:

# 1. health (Render 의 healthCheckPath 와 동일 — Rails health controller)
curl -i https://api.1pass.dev/healthz                       # 200 OK 기대
# 2. /up 도 동일 결과 — Rails 기본 health probe (load-balancer/uptime monitor 친화)
curl -i https://api.1pass.dev/up                            # 200 OK 기대
# 3. OIDC discovery
curl -i https://api.1pass.dev/.well-known/openid-configuration   # 200 + JSON
# 4. JWKS
curl -s https://api.1pass.dev/.well-known/jwks.json | jq '.keys | length'   # >= 1

Render 가 자동 probe 하는 endpoint 는 /healthz 입니다 (render.yaml healthCheckPath). /up 은 Rails 표준 health endpoint — 외부 모니터/로컬 체크에 동일하게 사용 가능. 두 엔드포인트 모두 routes.rb 에 정의되어 있고 동일한 health 결과를 반환합니다.

이어서 Render dashboard logs 5분 모니터 — error rate 0 확인.

롤백

코드만 롤백 (마이그가 backward-compatible)

Render dashboard → Deploys 탭 → 직전 green deploy → "Rollback to this deploy".

또는 git 기반:

git revert <bad-sha> && git push origin main
# logi-server 는 수동이므로 위 Manual Deploy 다시 트리거

마이그가 destructive 인 경우

코드 롤백 만 으로 부족 — 새 컬럼/제약을 read 하던 이전 코드가 깨짐. 절차:

1. 코드를 직전 green 으로 롤백 (위 절차)
2. SSH 로 rails db:rollback STEP=N RAILS_ENV=production (N = 되돌릴 마이그 수)
3. rails db:migrate:status 로 schema_migrations 상태 확인

destructive 마이그 합치기 전에 위 두 단계를 머릿속에서 미리 시뮬레이션할 것.

환경 변수

Render dashboard → 서비스 → Environment.

⚠️ API 로 env vars 수정 시 절대 collection PUT (PUT /v1/services/{id}/env-vars) 사용 금지. 전체 교체라 누락된 키가 사라짐 (2026-03-30 ainote 52→4개 유실 사고). 항상 개별 PUT 사용:

curl -X PUT "https://api.render.com/v1/services/<LOGI_WEB_SERVICE_ID>/env-vars/MY_KEY" \
  -H "Authorization: Bearer $RENDER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"value": "new-value"}'

env 변경 시 Render 가 자동으로 redeploy 트리거.

핵심 env 키 (변경 시 영향 큰 것)

• APNS_* (KEY_ID/TEAM_ID/TOPIC/ENV) — push 전체 영향
• APPLE_TEAM_ID, APPLE_KEY_ID, APPLE_PRIVATE_KEY — Sign in with Apple revoke
• SOLID_QUEUE_IN_PUMA=true, JOB_CONCURRENCY=1 — worker 통합
• ENFORCE_CANONICAL_RESOLUTION — ⚠️ 머지 후 canonical resolution 강제. flip 전 incident response §머지 race 참조.

Secret File

apns.p8 는 Render Secret Files (/etc/secrets/apns.p8) 로 마운트. 키 회전 시 dashboard 의 Secret Files 탭에서 교체 + redeploy. env var 가 아니므로 위 API 와 무관.