Document Library — Coolify 배포 가이드

GitHub 자동 배포(Coolify)로 운영한다. 이전 배포 플랫폼의 설정 파일은 제거했다.

배포 트리거

항목	값
Build Command	`pnpm install --no-frozen-lockfile && pnpm run build`
Start Command	`pnpm start:with-migrations` (= `pnpm db:migrate && pnpm start`)
Health Check	`/api/directory/readiness`
Node	`package.json` engines 기준

pnpm db:migrate(server/database-migrations.ts)가 dialect(PostgreSQL/MySQL)에 맞는 마이그레이션을 적용한다 — 용어 outbox(term_extraction_jobs) 포함.
시작 시 server/ensureSchema.ts 가 outbox 를 멱등 보강하므로, 마이그레이션이 안 돌아도 서버는 뜨고 큐 스키마는 확보된다.
@hohyun94 의존성은 file:vendor/*.tgz 라 GitHub Packages 토큰 없이 설치된다.

키	필수	설명
`NODE_ENV`	✔	`production`
`DATABASE_DIALECT`	✔	`postgresql` 또는 `mysql` (URL 프로토콜과 일치)
`DATABASE_URL`	✔	DB 연결 문자열
`ARCHIVE_API_KEY`	✔	아카이브 API 키
`JWT_SECRET`	✔	세션 서명
`ARCHIVE_CORS_ORIGINS`	✔	허용 오리진 — 새 Coolify 도메인으로 갱신(예전 배포 플랫폼 도메인 아님)
`DIRECTORY_PORTAL_API_KEY`	✔(권장)	원장(PortalConsole) 호출 키 — `glossary:read`/`glossary:write`
`DIRECTORY_SERVICE_URL`		DirectoryService/원장 주소(미설정 시 기본값)
`TERM_LINK_SYNC_INTERVAL_MS`		용어 추출 주기(기본 5분, 최소 30초)
`DISABLE_TERM_LINK_SYNC`		`true` 면 용어 추출 스케줄러 비활성
`EXPLORE_GATEWAY_URL`		ExploreGateway 오리진. 설정하면 셸 상단 검색의 질문이 게이트웨이 → 중앙 RAG 로 간다(정본). 미설정이면 질문 버튼을 켜지 않는다
`EXPLORE_GATEWAY_AUDIENCE`		위임 토큰 audience(기본 `explore-gateway`). 콘솔 소비자 등록의 `delegationAudiences` 와 일치해야 한다
`DOCUMENT_LIBRARY_SERVICE_CLIENT_SECRET`		콘솔이 발급한 이 포털의 소비자 시크릿(위임 토큰 경로 B). 브라우저에 내려가지 않는다
`EXPLORE_SERVICE_TOKEN`		게이트웨이가 이 포털 문서를 검색할 때 쓰는 서비스 토큰 — ExploreGateway `PORTAL_SERVICE_TOKENS_JSON["document-library"]` 와 같은 값. 비우면 어댑터 경로가 503

검색은 이 포털이 소유한다: 셸 결과는 게시판 색인에서 만든다(client/src/features/explore/useShellExplore.ts) — 화면 목록과 같은 규칙을 쓴다.
답변은 중앙이 정본이다: POST /api/explore/ask → ExploreGateway → RagService. 이 포털은 답을 만들지 않는다.
문서는 게이트웨이 색인에 합류한다: POST /api/explore/v1/search(서비스 토큰) 로 게시글을 kind=document 로 제공한다.
구성 여부는 GET /api/explore/capabilities 가 알려준다 — 미구성이면 화면이 질문 버튼을 켜지 않는다.
위임 토큰은 Directory 사용자 주체로만 발급되므로 directory 모드에서만 동작한다(local 모드에는 위임할 주체가 없다).
콘솔 등록: PORTAL_CONSOLE_TOKEN_CONSUMERS_JSON 에 clientId: "document-lib", delegationAudiences: ["explore-gateway"], delegationScopes: ["search:read"].

스키마: pnpm db:migrate(PG 0001 / MySQL 0011) + 시작 시 server/ensureSchema.ts 보강.
적재: 게시글 생성(server/archive-api-db.ts)과 전체 교체 저장(server/archive-db.ts) 뒤 큐에 적재한다.
반영: 스케줄러(startTermExtractionScheduler)가 원장에 연결/해제를 push 한다.
표시/검색: GET /api/archive/posts/:id/terms(상세 용어), GET /api/archive/search/terms?q=(용어 검색) — 클라이언트는 PostTerms·TermSearchPanel.
DIRECTORY_PORTAL_API_KEY 가 없으면 스케줄러·연결은 조용히 비활성이다(저장·표시는 정상).