Docker를 도입하고 싶지 않거나 프로세스와 nginx를 세밀하게 제어하고 싶은 사람을 위한 경로입니다. 프런트엔드와 백엔드는 독립적인 두 가지입니다: 백엔드는 Node 프로세스 하나, 프런트엔드는 정적 파일 묶음입니다.
1.툴체인 설치
필요한 것: Node.js 20+, pnpm 8.15.4(저장소 packageManager에 고정된 버전, corepack enable로 자동 획득 권장), nginx(정적 사이트 + HTTP 리버스 프록시가 가능한 웹 서버라면 무엇이든). better-sqlite3 컴파일에는 python3, make, g++가 필요합니다 — Linux는 build-essential 설치, macOS는 xcode-select --install 실행.
2.백엔드 실행 (포트 3000)
저장소 루트에서 먼저 pnpm install --frozen-lockfile(workspace 패키지)을 실행합니다. 이어서 api/로 들어가 npm ci(api는 npm + package-lock.json을 사용하며 pnpm workspace에 포함되지 않음), npm run build를 실행하고 node dist/main으로 시작합니다(프로덕션은 pm2 start dist/main 권장). api/.env가 준비되어 있어야 하며, SQLite는 DATABASE_PATH 위치에 자동 생성됩니다. curl http://127.0.0.1:3000/health가 200을 반환하면 됩니다.
3.프런트엔드 빌드와 호스팅 (포트 5180)
pnpm --filter @yinjie/app build를 실행하면 산출물이 apps/app/dist/에 생성됩니다. 저장소에 포함된 nginx 템플릿은 apps/app/nginx/default.conf.template입니다: 그 안의 APP_API_UPSTREAM 플레이스홀더를 http://127.0.0.1:3000으로 바꾸고, 리슨 포트와 정적 루트를 실제 값으로 수정한 뒤 nginx -t가 통과하면 리로드해서 바로 사용할 수 있습니다. 템플릿에는 /api, /socket.io 프록시와 SPA 폴백이 이미 포함되어 있습니다.
4.운영 엔드포인트 확인
X-Admin-Secret 헤더를 붙여 /api/admin/stats에 접근하면 200 + JSON이 반환되어야 합니다. 401이 나오면 시크릿이 틀렸거나 리버스 프록시가 X-Admin-Secret 헤더를 삼킨 것입니다(해결 방법은 "리버스 프록시와 HTTPS" 참고).
관련 질문
Enclave를 셀프 호스팅할 수 있나요? 어렵나요?
가능하며, 난이도는 일반적인 web 서비스를 운영하는 것과 비슷합니다. docker compose를 사용해 봤다면 세 단계로 자신의 인스턴스를 가질 수 있습니다: 저장소 클론, .env 복사, docker compose up. API·프런트엔드·데이터베이스·벡터 인덱스가 모두 내 서버에서 실행됩니다.Enclave를 셀프 호스팅하려면 무엇이 필요한가요? GPU가 필요한가요?
반드시 GPU가 필요하지는 않습니다. 클라우드 모델 API(OpenAI, Anthropic 등)를 사용한다면 Docker를 돌릴 수 있는 평범한 서버나 가정용 머신으로 충분합니다 — 추론은 클라우드에서 이루어지고, 본 기기는 앱과 데이터베이스만 실행합니다. 로컬 모델(Ollama / vLLM)로 오프라인 추론을 하려는 경우에만 그에 맞는 VRAM과 연산 능력이 필요합니다.Enclave는 어떤 데이터베이스를 사용하나요? 직접 구축해야 하나요?
별도 구축이 필요 없습니다. Enclave는 데이터베이스와 벡터 인덱스를 내장하고 있어, docker compose로 띄울 때 다른 구성 요소와 함께 로컬에서 실행됩니다. 문서, 대화, 기억은 모두 구조화되어 그 안에 저장되며, 셀프 호스팅 모드에서는 이 데이터가 당신의 기기에만 존재합니다.