DocumentLibrary 모듈형 설치 및 연동
DocumentLibrary는 DirectoryService, FileStore, UiCenter가 없어도 독립적으로 설치·운영할 수 있다. portal-foundation은 애플리케이션 빌드에 항상 포함되며, UiCenter는 중앙 브랜딩·테마·메뉴 profile을 여러 포털에 적용할 때만 선택적으로 연결한다. FileStore는 첨부파일 backend가 필요한 경우에만 포털별로 선택한다.
| 구성 | DocumentLibrary 동작 | 필수 입력 |
|---|---|---|
| 단독 local | 자체 MySQL, 단독 운영 조직, 초기 관리자 | MySQL URL, local admin credential |
| DirectoryService | 중앙 조직·사용자·권한과 PKCE 로그인 사용 | MySQL URL, DirectoryService HTTPS URL |
| 단독 + FileStore | local identity와 선택 storage backend 결합 | 위 local 값, FileStore URL |
| 중앙 UI profile 사용 | 위 구성에 중앙 UI profile provider를 추가 | UiCenter URL. 포털 기본 UI는 항상 local/cached fallback 유지 |
지원 범위: 현재 DocumentLibrary의 실제 migration은 MySQL/MariaDB용이다. PostgreSQL은 기존 schema와 migration이 완전하게 구현되기 전까지
/setup선택지에 표시하지 않는다.
DB-less first-run 흐름
DATABASE_URL을 비워서 서버를 실행하면 server는 종료하지 않고 /api/setup/status를 제공한다. client root guard는 일반 로그인·관리 화면 대신 /setup wizard를 표시한다. Wizard는 아래 순서로 동작한다.
| 단계 | 실제 처리 | 보안 처리 |
|---|---|---|
| 1. 연결 검증 | MySQL/MariaDB URL 연결·version 확인 | URL 및 password를 응답·로그에 반환하지 않음 |
| 2. identity 선택 | LOCAL 또는 DIRECTORY 선택 | DIRECTORY 선택에는 HTTPS DirectoryService URL을 요구 |
| 3. optional services | FileStore·UiCenter URL을 선택 입력 | remote URL은 HTTPS만 허용, localhost 개발 환경만 HTTP 허용 |
| 4. install | 10개 existing MySQL migration 적용, runtime pool 활성화 | production은 DOCUMENT_LIBRARY_SETUP_TOKEN header가 필요 |
| 5. LOCAL provisioning | 단독 운영 조직 및 initial admin 생성 | password는 scrypt hash로만 managed_users에 저장 |
| 6. configuration persistence | identity와 optional service URL을 setup table에 저장 | secret·DB URL·admin password를 setup status/integration API에 노출하지 않음 |
MySQL/MariaDB의 64자 identifier 제약을 고려해 setup migration runner는 기존 Drizzle migration의 긴 foreign-key constraint 이름만 결정적으로 축약한다. 테이블 정의와 FK 관계 자체는 변경하지 않는다. 설치 target은 비어 있는 database여야 하며, 중단된 partial schema는 설치 wizard가 덮어쓰지 않고 복구 또는 새 database 사용을 요청한다.
환경변수 우선순위
.env.example을 복사해 사용한다. Wizard가 저장한 database configuration보다 environment variable이 우선하므로, immutable deployment 또는 secret manager를 사용하는 환경은 필요한 값만 environment로 inject할 수 있다.
| 변수 | 목적 | 공개 API 노출 |
|---|---|---|
DATABASE_URL | environment-managed MySQL connection | 절대 노출하지 않음 |
DOCUMENT_LIBRARY_SETUP_TOKEN | production install action 보호 | 절대 노출하지 않음 |
DOCUMENT_LIBRARY_IDENTITY_MODE | local 또는 directory override | mode만 integration API에 표시 |
DIRECTORY_SERVICE_URL | 중앙 identity provider | sanitized base URL만 admin integration UI에 표시 |
DOCUMENT_LIBRARY_LOCAL_ADMIN_PASSWORD | legacy/environment local admin fallback | 절대 노출하지 않음 |
FILE_STORE_BASE_URL | 선택형 attachment backend | sanitized base URL만 admin integration UI에 표시 |
UICENTER_BASE_URL | 선택형 central UI profile provider | sanitized base URL만 admin integration UI에 표시 |
배포와 장애 fallback
배포 플랫폼·Railway·온프레미스 배포 모두 DB 없는 첫 기동에서는 wizard로 시작할 수 있다. provider environment variable 또는 deploy action의 실제 변경은 setup UI의 명시적 승인 단계나 배포 운영자의 승인 후에만 수행한다. 이번 구현은 provider의 secret을 자동 변경하지 않는다.
DirectoryService 또는 UiCenter가 미연결·장애인 경우 DocumentLibrary는 local identity 및 portal-foundation의 local/cached visual profile로 동작을 유지한다. FileStore가 미연결이면 attachment backend 관련 기능만 unavailable로 표기하며, identity 또는 기본 portal UI를 중단시키지 않는다.