# MCP Hub Connector 환경별 설치 가이드

> **대상**: 사내 인프라 담당자 — 가상화 / 클라우드 환경에서 커넥터 설치
> **선행 조건**: 기본 설치 가이드 ([Connector 설치 가이드](/guides/connector-installation)) 1~3장 숙지
> **본 문서는 환경별 차이만 다룸** — 페어링 / secrets / 업데이트 등 공통 절차는 기본 가이드 참고
>
> secrets 디렉토리는 기본 가이드의 `/etc/mcp-connector/secrets` 그대로 사용 — 환경에 따라 경로만 조정.

---

## 환경별 권장도

| 환경                                       | 권장도       | 설치 난이도 | 비고                                              |
| ------------------------------------------ | ------------ | ----------- | ------------------------------------------------- |
| **Linux 서버 (베어메탈 / 일반 VM)**        | ✅ 가장 권장 | 쉬움        | 기본 가이드 그대로                                |
| **Nutanix AHV / VMware vSphere 등 가상화** | ✅ 권장      | 쉬움        | VM 생성만 추가, 그 위는 일반 Linux                |
| **AWS EC2 / Azure VM / NCP / GCP**         | ✅ 권장      | 쉬움        | VPC 안에 배치 — VPN/Direct Connect 로 사내망 연결 |
| **Windows Server + WSL2 + Ubuntu**         | △ 가능       | 중간        | 부득이한 경우만. 셋업 시간 1~2 시간               |
| **Docker Desktop (Windows / macOS)**       | △ PoC 만     | 쉬움        | 24/7 가동 어려움. 운영 X                          |

---

## 1. Nutanix AHV / 일반 가상화 (vSphere, KVM 등)

### 1-1. VM 생성 시 권장 사양

| 항목     | 값                                  |
| -------- | ----------------------------------- |
| OS       | Ubuntu 22.04 LTS / RHEL 8 / Rocky 9 |
| vCPU     | 2                                   |
| 메모리   | 2 GB (도구 호출량 많으면 4 GB)      |
| 디스크   | 10 GB (시스템 5 + 로그/이미지 5)    |
| 네트워크 | 사내망 — DB / ERP 와 같은 VLAN 권장 |

### 1-2. VM 생성 후 절차

1. SSH 로 VM 접속
2. Docker 설치
   ```bash
   # Ubuntu
   curl -fsSL https://get.docker.com | sudo sh
   sudo usermod -aG docker $USER
   newgrp docker
   ```
3. 이후 [기본 가이드 4장](connector-installation-guide.md#4-설치-명령어-사내-개발자에게-전달) 으로 진행

### 1-3. Nutanix 특이사항

- **AHV 의 ARM64 / x86 구분**: 일반적으로 x86. Connector 이미지는 `linux/amd64` + `linux/arm64` 모두 빌드되어 있어 자동 적합
- **VM Time Sync**: NTP 설정 필수 — mTLS 인증서 검증이 시간에 민감
- **Snapshot / 복제**: 운영 안정성 좋아짐. 단 **인증서가 들어있는 docker volume** (`mcp-hub-connector-state-*`) 도 함께 백업 필수

---

## 2. 클라우드 (AWS / Azure / NCP / GCP)

### 2-1. 권장 구성

```
                            ┌──── VPC ─────────────────────┐
                            │                              │
    [WRKS AI Cloud] ────────│──→ [커넥터 EC2]              │
                            │     (Public Subnet 권장 X,    │
                            │     Private Subnet + NAT 권장) │
                            │                              │
                            │     ▼                        │
                            │  ┌─ VPN / Direct Connect ─┐ │
                            │  │  (사내 DC 와 연결)        │ │
                            │  └────────────────────────┘ │
                            └──────────────────────────────┘
                                          ↓
                                  [사내 DB / ERP]
```

**핵심**: 커넥터는 **Private Subnet + NAT Gateway** 권장. Public IP 부여 불필요 (outbound 만).

### 2-2. AWS EC2 — 단계별

#### Step 1. EC2 인스턴스 생성

| 항목           | 권장값                                        |
| -------------- | --------------------------------------------- |
| AMI            | Amazon Linux 2023 또는 Ubuntu 22.04           |
| 인스턴스 타입  | `t3.small` (2 vCPU / 2 GB)                    |
| Subnet         | Private Subnet (NAT Gateway 통과)             |
| Security Group | inbound 22 (관리용 SSH) 만, outbound 443 허용 |
| IAM 역할       | (선택) Secrets Manager 사용 시 별도           |

#### Step 2. NAT Gateway 설정 확인

- VPC → NAT Gateway 있는지 확인
- Private Subnet 의 라우팅 테이블이 NAT 으로 지정돼 있는지

#### Step 3. Docker + 커넥터 설치

```bash
# Amazon Linux 2023
sudo dnf install -y docker
sudo systemctl enable --now docker
sudo usermod -aG docker ec2-user

# 또는 Ubuntu
curl -fsSL https://get.docker.com | sudo sh
sudo usermod -aG docker $USER
```

이후 기본 가이드 4장 절차.

#### Step 4. (선택) AWS Secrets Manager 연동

평문 `.env` 파일 대신 Secrets Manager 사용 가능 — entrypoint 스크립트 또는 `awscli` 로 fetch 후 `/var/secrets/*.env` 에 적기. 본 가이드 범위 밖 — 필요 시 별도 문의.

### 2-3. Azure VM

| 항목     | 권장값                         |
| -------- | ------------------------------ |
| OS       | Ubuntu 22.04 LTS               |
| 크기     | `Standard_B2s` (2 vCPU / 4 GB) |
| 네트워크 | Private VNet + Azure NAT       |
| NSG      | outbound 443 허용              |

설치 절차는 위 EC2 와 동일.

### 2-4. NCP (Naver Cloud Platform)

- Server > Server 생성 → Ubuntu 또는 CentOS
- VPC > Subnet 의 NAT Gateway 활성화
- ACG (Access Control Group): outbound 443 허용

### 2-5. 클라우드 공통 유의

- **사내망 → 클라우드 VPC 연결 필수**: VPN / Direct Connect / ExpressRoute. 커넥터가 사내 DB 에 접근해야 함
- **이미지 자동 업데이트 X**: AMI / 이미지 sticky 태그 사용 X — Studio 가 알려주면 수동 업데이트
- **로그 / 모니터링**: CloudWatch / Azure Monitor 등에 컨테이너 로그 수집 권장 (사고 추적)

---

## 3. Windows Server + WSL2 + Ubuntu 중첩 구성

> **권장도 △** — Linux VM 가능하면 그쪽으로. 부득이한 경우만.

### 3-1. 셋업이 오래 걸리는 이유

1. WSL2 활성화 (재부팅 1~2회)
2. Ubuntu 배포판 설치 + 초기 설정
3. WSL2 안에 Docker 설치
4. 자동 시작 / systemd 설정
5. 네트워크 (WSL2 NAT) 디버깅

총 1~2 시간. **단축 팁** 아래 정리.

### 3-2. 사전 확인

| 항목             | 요구사항                                                    |
| ---------------- | ----------------------------------------------------------- |
| Windows Server   | 2019 또는 2022 (Datacenter / Standard)                      |
| Hyper-V / 가상화 | BIOS 에서 Intel VT-x / AMD-V 활성화                         |
| WSL2             | Windows Server 2022 부터 정식 지원 (2019 는 별도 패치 필요) |

### 3-3. WSL2 + Ubuntu 설치

```powershell
# PowerShell (관리자)
wsl --install -d Ubuntu-22.04
# 재부팅 후 Ubuntu 사용자명/비밀번호 설정
```

### 3-4. systemd 활성화 (Docker 자동 시작용)

```bash
# Ubuntu (WSL2 안)
sudo tee /etc/wsl.conf > /dev/null <<EOF
[boot]
systemd=true
EOF
```

```powershell
# PowerShell — WSL2 재시작
wsl --shutdown
wsl
```

### 3-5. Docker 설치 (WSL2 Ubuntu 안)

```bash
curl -fsSL https://get.docker.com | sudo sh
sudo systemctl enable --now docker
sudo usermod -aG docker $USER
exit  # 새 shell 로 재진입 (그룹 권한)
```

### 3-6. Windows 부팅 시 WSL2 자동 시작

작업 스케줄러 (Task Scheduler) 에 등록:

| 항목    | 값                                                   |
| ------- | ---------------------------------------------------- |
| Trigger | At startup                                           |
| Action  | `wsl -d Ubuntu-22.04 -u root systemctl start docker` |
| 사용자  | SYSTEM                                               |
| 권한    | 가장 높은 권한으로 실행                              |

### 3-7. 커넥터 컨테이너 실행

이후 [기본 가이드 4장](connector-installation-guide.md#4-설치-명령어-사내-개발자에게-전달) 명령 — WSL2 Ubuntu 안에서 실행.

### 3-8. Windows 특이 트러블슈팅

| 증상                           | 해결                                                                                                                                        |
| ------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------- |
| `wsl --install` 가 안 됨       | Hyper-V 기능 활성화 필요 (서버 관리자 → 기능 추가)                                                                                          |
| Docker 가 systemd 없이 안 켜짐 | `/etc/wsl.conf` 의 `systemd=true` + `wsl --shutdown` 후 재진입                                                                              |
| 사내 DNS 가 안 풀림            | WSL2 의 `/etc/resolv.conf` 가 매번 자동 생성 — 고정 DNS 필요 시 `/etc/wsl.conf` 에 `[network] generateResolvConf = false` 추가 후 수동 작성 |
| 재부팅 후 Docker 안 켜짐       | 위 3-6 작업 스케줄러 누락                                                                                                                   |

> **추천**: Windows Server 환경이면 Hyper-V 로 Ubuntu VM 1대 만드는 게 WSL2 보다 단순하고 안정적입니다 (관리자 협의).

---

## 4. Docker Desktop (Windows / macOS) — PoC 전용

- PoC / 개발 환경 만 사용. 운영 X
- 사용자 로그아웃 / 컴퓨터 절전 시 컨테이너 정지
- Studio 의 페어링 화면에서 "Docker Desktop" 선택 시 `host.docker.internal` 같은 가상 호스트 매핑 명령이 자동 생성됨

---

## 5. 환경 별 체크리스트

| 환경              | 1순위 점검                                                    |
| ----------------- | ------------------------------------------------------------- |
| 일반 Linux VM     | `docker ps`, `docker logs`, 사내 DB telnet                    |
| Nutanix / vSphere | NTP 시간 동기, snapshot 백업에 docker volume 포함             |
| AWS / Azure / NCP | VPN / Direct Connect 연결, Private Subnet + NAT, outbound 443 |
| Windows + WSL2    | systemd 활성화, 작업 스케줄러 자동 시작, DNS 수동 설정        |

---

## 6. 문의

- 환경별 특수성 / 사전 협의 사항: WRKS 담당자에게 연락
- 사내 네트워크 / 보안 검토: 사내 인프라 / 보안팀과 협업

> 같이 보세요:
>
> - 기본 커넥터 설치 → [Connector 설치 가이드](/guides/connector-installation)
> - 툴킷 사용 → [Toolkit 사용 가이드](/guides/toolkit-usage)
> - DB 별 연동 상세 → [DB 연동 가이드](/guides/db-connection)