배포 · Minara Agent

대부분의 사용자는 데스크톱 앱이나 로컬 실행을 사용하면 됩니다. 영구 데이터 볼륨을 갖춘 재현 가능한 서버 구성이 필요할 때 Docker를 사용하세요.

배포 형태 선택

소스 checkout의 루트에서 실행하세요.

pnpm docker

첫 실행은 .env.example을 .env로 복사한 뒤 종료합니다. LLM provider 자격 증명과 MINARA_API_KEY를 최소한 입력한 뒤 다시 실행하세요. 다음이 시작됩니다.

자주 쓰는 작업:

pnpm docker:up
pnpm docker:down
pnpm docker:logs
pnpm docker:rebuild

실행 중인 Agent에 터미널 세션이 필요하면 docker exec -it minara-agent node dist/gateway/cli.js를 사용하세요.

Docker 스택은 Minara 상태를 이름 있는 볼륨에 저장합니다. SQLite 데이터, 감사 기록, 워크스페이스 파일, 인증 프로필, 로그가 포함됩니다. 컨테이너를 다시 만들어도 이 볼륨은 유지하세요.

중요한 업그레이드 전에는 데이터 볼륨을 백업하거나 SQLite 데이터베이스를 내보내세요. 그 후 같은 볼륨을 연결한 채 컨테이너를 다시 빌드하거나 교체합니다. DB 마이그레이션은 Agent 시작 시 실행됩니다.

SQLite는 하나의 활성 writer에 맞게 설계되었습니다. 하나의 볼륨은 상태를 소유하는 하나의 Agent가 사용해야 합니다. 복제본을 추가할 경우 쓰기는 그 소유자를 거치게 하고, 여러 독립 writer가 같은 DB를 마운트하지 않게 하세요.

이유가 없으면 gateway는 localhost에 유지하세요. 원격 gateway는 금융 및 계정 작업에 닿을 수 있으므로 GATEWAY_AUTH_TOKEN을 설정하고 TLS를 종료하는 리버스 프록시를 앞에 두어야 합니다.

자격 증명을 이미지에 넣지 마세요. 로컬 Docker Compose에서는 .env를, 호스팅 배포에서는 시크릿 저장소나 런타임 환경 변수를 사용하세요. 시크릿을 commit하거나 이미지에 구워 넣지 마세요.

gateway는 기본 컨테이너 상태 점검용으로 GET /healthz를 제공합니다. 더 폭넓은 로컬 설정 점검은 minara doctor로 실행하세요.

Web UI가 필요 없다면 Agent 이미지를 직접 빌드하고 실행할 수 있습니다.

pnpm docker:build
pnpm docker:run

이 방식은 8080 포트에 gateway를 노출하고 minara-data 볼륨을 마운트합니다. 자격 증명은 호스트 환경이나 배포 플랫폼에서 제공하고 명령 기록에 남기지 마세요.