Skip to main content

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 탐색 구현은 운영 배포나 데이터 변경을 수행하지 않는다.

관련 문서