> ## Documentation Index
> Fetch the complete documentation index at: https://docs.myrmagent.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# 단일 VM Docker Compose

> 하나의 Linux VM에서 Myrm 제어 평면과 사용자별 샌드박스 배포

## 개요

공식 지원되는 기업 프라이빗 배포는 **하나의 Linux VM**에서 Docker Compose로 실행됩니다. 제어 평면, WebUI, PostgreSQL, Redis, Caddy(자동 TLS)가 함께 시작되며, 제어 평면이 직원별 샌드박스 컨테이너와 영구 볼륨을 하나씩 생성합니다.

> [!NOTE]
>
> 이 페이지는 **OIDC SSO와 중앙 감사**가 필요한 기업 셀프 호스팅용입니다. 개인 사용은 [데스크톱 앱](/docs/ko/getting-started/desktop-app) 또는 [로컬 배포](/docs/ko/getting-started/local-deployment)를 사용하세요.

## 아키텍처

```
브라우저 ──HTTPS──► Caddy ──► WebUI (3000)
                      │
                      └─────► 제어 평면 (8003)
                                    │
                     ┌──────────────┼──────────────┐
                     ▼              ▼              ▼
               PostgreSQL        Redis        호스트 Docker
                                                 │
                                    ┌────────────┴────────────┐
                                    ▼                         ▼
                              사용자별 샌드박스            영구 볼륨
```

* **Caddy**가 TLS를 처리하고 `/api`, `/proxy`, `/ws`, `/llm-relay`, `/tool-relay`, `/tunnel-relay`, `/vnc`를 제어 평면으로, 나머지는 WebUI로 프록시합니다.
* 제어 평면은 호스트 Docker 소켓으로 샌드박스를 만들고 HTTP/WebSocket 트래픽을 전달합니다.
* PostgreSQL은 제어 평면 데이터를, 각 Docker 볼륨은 직원별 워크스페이스와 메모리를 보관합니다.

## 사전 요구 사항

* Ubuntu 22.04/24.04, 8 vCPU / 16 GB RAM
* Docker 24+ 및 Compose v2
* 도메인 DNS 레코드, 80/443 포트 개방
* OIDC 자격 증명 공급자(Okta, Entra ID, Keycloak 등)
* 서명된 기업 라이선스 JWT와 공급업체 공개 키
* 선택: 더 강한 격리를 위한 호스트 `runsc`(gVisor)

## 빠른 시작

```bash theme={null}
cd myrm-control-plane
cp deploy/compose/.env.example deploy/compose/.env

# .env 편집:
#   MYRM_DOMAIN, POSTGRES_PASSWORD, DOCKER_GID
#   MYRM_CP_ENTERPRISE_LICENSE_KEY / _PUBLIC_KEY
#   MYRM_CP_JWT_SECRET, MYRM_CP_MASTER_ENCRYPTION_KEY
#   MYRM_CP_OIDC_* 및 MYRM_CP_ADMIN_USER_IDS

docker compose -f deploy/compose/docker-compose.yml up -d
docker compose -f deploy/compose/docker-compose.yml ps
```

`DOCKER_GID`는 호스트 Docker 소켓의 그룹 id입니다.

```bash theme={null}
stat -c '%g' /var/run/docker.sock
```

기본 샌드박스 런타임은 `docker`입니다. `runsc`가 설치되어 있으면 `.env`에서 `MYRM_CP_RUNTIME=docker_gvisor`로 설정하세요.

## 주요 변수

| 변수 | 용도 |
| - | - |
| `MYRM_DOMAIN` | 공개 호스트 이름, Caddy가 인증서를 자동 발급 |
| `POSTGRES_PASSWORD` | PostgreSQL 비밀번호이자 제어 평면 DSN |
| `DOCKER_GID` | 호스트 Docker 소켓 그룹 id |
| `MYRM_CP_ENTERPRISE_LICENSE_KEY` | 서명된 라이선스 JWT |
| `MYRM_CP_ENTERPRISE_LICENSE_PUBLIC_KEY` | 오프라인 검증용 공급업체 공개 키 |
| `MYRM_CP_JWT_SECRET` | API 토큰 서명 키 |
| `MYRM_CP_MASTER_ENCRYPTION_KEY` | 64자리 16진수, 샌드박스 비밀 암호화 |
| `MYRM_CP_OIDC_ISSUER_URL` / `_CLIENT_ID` / `_CLIENT_SECRET` | 기업 SSO |
| `MYRM_CP_ADMIN_USER_IDS` | 첫 관리자(쉼표 구분) |
| `MYRM_CP_RUNTIME` | `docker`(기본) 또는 `docker_gvisor` |

OIDC 리디렉션 URI:

```
https://<MYRM_DOMAIN>/api/auth/oauth/oidc/callback
```

## 첫 관리자와 조직

1. OIDC로 한 번 로그인합니다.

2. 해당 사용자를 owner로 조직을 생성합니다.

   ```bash theme={null}
   docker compose -f deploy/compose/docker-compose.yml exec control-plane \
     python -m myrm_control_plane.bootstrap --org "Company" --admin-email admin@company.com
   ```

3. 출력된 `owner_user_id`를 `.env`의 `MYRM_CP_ADMIN_USER_IDS`에 넣고 제어 평면을 재시작합니다.

   ```bash theme={null}
   docker compose -f deploy/compose/docker-compose.yml up -d control-plane
   ```

브라우저 최초 실행 마법사는 계획 중이며, CLI가 기존 수동 SQL + JWT API 절차를 대체합니다.

## 기존 리버스 프록시 사용

Caddy는 선택 사항입니다. `caddy` Compose 프로필(`.env`의 `COMPOSE_PROFILES=caddy`)로 실행됩니다. 같은 호스트에 Nginx/ALB가 이미 있다면 해당 줄을 제거하고 다음 규칙으로 라우팅하세요.

| 경로 | 업스트림 |
| - | - |
| `/api`, `/proxy`, `/ws`, `/llm-relay`, `/tool-relay`, `/tunnel-relay` | `127.0.0.1:8003` |
| `/vnc` | `127.0.0.1:8002` |
| 나머지 | `127.0.0.1:3000` |

기존 프록시에서 TLS를 종료하고 CP API 포트를 공용 인터넷에 직접 노출하지 마세요.

## 운영

```bash theme={null}
# 로그
docker compose -f deploy/compose/docker-compose.yml logs -f control-plane

# 재시작
docker compose -f deploy/compose/docker-compose.yml restart

# 업그레이드(.env에서 MYRM_VERSION 고정 후)
docker compose -f deploy/compose/docker-compose.yml pull
docker compose -f deploy/compose/docker-compose.yml up -d
```

**백업**: 내장 스크립트를 실행합니다(PostgreSQL + `cp-data` + SHA256 + 보존 기간):

```bash theme={null}
BACKUP_DIR=/srv/myrm-backups RETENTION_DAYS=30 ./deploy/compose/backup.sh
```

복원은 파괴적이며 반드시 `--yes`를 명시해야 합니다. 트래픽 전환 전에 새 VM에서 검증하세요.

## 범위와 제한

* **단일 VM 전용**: HA, 클러스터링, 다중 리전 장애 조치 없음.
* **소규모 팀**; 실제 워크로드로 벤치마크한 뒤 확장하거나 팀별로 분리하세요.
* **OIDC만 지원**: SAML과 SCIM은 포함되지 않습니다.
* **BYOK/KMS와 에어갭 모드 미지원.**
* **Linux 전용**(샌드박스 런타임이 호스트 Docker daemon 사용).
* 지원 OS: Ubuntu 22.04/24.04, 공식 저장소의 Docker.

## 보안 참고

* Docker 소켓 마운트는 제어 평면에 호스트 컨테이너 제어권을 부여합니다. SSH와 Docker 접근을 신뢰할 수 있는 관리자로 제한하세요.
* 샌드박스는 권한을 낮추고 불필요한 capability를 제거하며 CPU/메모리/PID 제한을 적용합니다. Docker 보안 옵션으로 seccomp/AppArmor를 추가합니다. 더 강한 격리가 필요하면 `runsc`를 설치하고 `docker_gvisor`를 사용하세요.
* 직원별로 샌드박스와 볼륨이 분리됩니다. 관리자는 감사 이벤트와 사용량을 검토할 수 있으며, 보존 기간과 접근 권한은 회사 정책에 따라 설정하세요.
* `.env`를 버전 관리에 커밋하지 마세요. JWT/Master Key 교체는 계획된 마이그레이션 절차로 수행하세요.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.