code-server와 OCI 운영 경계
소스 편집·프런트엔드 검증과 OCI Docker 운영의 역할 구분 및 영속 데이터 보존 원칙
목적과 근거
이 문서는 저장소의 AGENTS.md와 Knowledge API 구현에서 확인된 환경 규칙을 정리한다. OCI의 실제 Compose, 호스트 디렉터리, Nginx Proxy Manager 설정을 조사한 운영 절차서는 아니다.
code-server에서 수행하는 작업
code-server 컨테이너는 소스 편집, Git, Codex 작업과 프런트엔드 검증 환경이다. Node.js와 npm을 사용하며 Docusaurus·TypeScript·React 구조를 유지한다.
저장소 루트에서 다음 검증을 수행한다.
npm run typecheck
npm run build
git diff --check
Docker CLI와 Docker socket은 이 환경의 기본 전제가 아니다. 백엔드 Python 테스트는 OCI Docker 런타임 또는 별도로 준비된 테스트 런타임을 사용한다.
OCI와 Docker 운영
Docker 빌드·재시작·Compose 변경·배포는 OCI 호스트에 SSH로 접속해서 수행하는 운영 작업이다. 외부 HTTPS 접근은 Nginx Proxy Manager를 사용한다는 프로젝트 규칙이 있다. 실제 컨테이너 이름, 포트 매핑, 인증 및 프록시 설정은 운영 환경에서 별도로 확인해야 한다.
소스 작업을 마친 사실만으로 배포가 완료된 것은 아니다. 배포 작업 전에는 기존 영속 볼륨과 환경 설정을 확인해야 하며 이 문서에는 미확인 배포 명령을 제시하지 않는다.
영속 데이터와 배포 문서
Knowledge API의 원본 파일은 /app/uploads에 저장되고 SQLite의 기본 경로는 /app/data/knowledge.db다. KNOWLEDGE_DB_PATH는 저장소 밖의 절대 경로를 지정한다. 파일과 DB의 지속 디렉터리는 소스 트리 밖에 두고 컨테이너에 마운트한다.
- 기존 DB를 삭제하거나 재생성하지 않는다.
- 기존 업로드 파일을 삭제하거나 이동하지 않는다.
.env, API 키, 업로드, DB, 생성된 런타임 산출물은 Git에 추가하지 않는다.- 분석과 사용자 검토본은 별도 데이터다. 검토 저장은 Wiki Markdown 생성이 아니다.
구체적인 API 계약과 볼륨 설정 예시는 Knowledge API 분석 설계의 Docker / OCI 영속 볼륨 절을 확인한다. 해당 문서의 예시 호스트 경로는 실제 OCI 설정을 확인한 값이 아니다.
확인할 사항
배포를 수행할 때 실제 Compose 위치, 기존 볼륨, 백업 방식, 실행 사용자 권한과 프록시·인증 구성을 먼저 확인한다. 이번 Wiki 탐색 구현은 운영 배포나 데이터 변경을 수행하지 않는다.