목적: macOS(Apple Silicon)에서 Azure Cosmos DB for NoSQL 에뮬레이터를 Docker로 실행하고, 백엔드(FastAPI) 및 VS Code에서 연결/테스트하는 방법을 한 번에 정리합니다.
대상: macOS(M1/M2/M3/M4), Docker Desktop, VS Code 사용자

아키텍처 개요

[Vue 3 SPA]  →  http://localhost:8000 (FastAPI)
                       ↓
             https://localhost:8081 (Cosmos 에뮬레이터, HTTPS)
                        └─ Explorer UI : 1234 (HTTP 또는 HTTPS)

1) 사전 준비

Tip: Docker Desktop을 실행한 상태에서 아래 단계를 진행하세요.

2) 에뮬레이터 컨테이너 실행

# 로컬 데이터 저장 경로
DATA_DIR="$HOME/.cosmos-emulator-data"
mkdir -p "$DATA_DIR"

# 기존 컨테이너 정리 후 실행
docker rm -f cosmos-emu 2>/dev/null || true
docker run -d --name cosmos-emu \
  -p 8081:8081 -p 1234:1234 \
  -v "$DATA_DIR":/data \
  mcr.microsoft.com/cosmosdb/linux/azure-cosmos-emulator:vnext-preview \
  --protocol https \
  --enable-explorer

# 상태 확인 (로그에 "PostgreSQL=OK, Gateway=OK, Explorer=OK" 반복되면 정상)
docker ps --filter name=cosmos-emu
docker logs cosmos-emu | tail -n 30

3) HTTPS(8081) 인증서 신뢰 설정

참고: URL(https://localhost:8081/_explorer/emulator.pem)에서 pem을 직접 받으면 간혹 JSON 에러가 저장됩니다. 아래처럼 TLS에서 직접 추출하는 방식이 가장 확실합니다.

# 1) 인증서 추출(8081의 첫 번째 CERT 블록 저장)
openssl s_client -connect localhost:8081 -servername localhost -showcerts </dev/null 2>/dev/null \
| sed -n '/BEGIN CERTIFICATE/,/END CERTIFICATE/p' \
| awk 'BEGIN{p=0} /BEGIN CERTIFICATE/{p=1} {if(p)print} /END CERTIFICATE/{exit}' \
> ~/Downloads/cosmos-emulator.pem

# 2) 인증서 파일 확인 ("-----BEGIN CERTIFICATE-----" 확인)
head -n 3 ~/Downloads/cosmos-emulator.pem

# 3) DER 형식으로 변환(가끔 더 안정적으로 임포트됨)
openssl x509 -in ~/Downloads/cosmos-emulator.pem -outform der \
  -out ~/Downloads/cosmos-emulator.cer

# 4) 시스템 키체인에 "신뢰 루트"로 추가(암호 입력 필요)
sudo security add-trusted-cert -d -r trustRoot \
  -k /Library/Keychains/System.keychain \
  ~/Downloads/cosmos-emulator.cer

# 5) 등록 확인
security find-certificate -c "localhost" /Library/Keychains/System.keychain

Keychain Access → System 키체인 → localhost 인증서 더블클릭 → Always Trust 적용.

이 인증서는 SDK/백엔드가 붙는 HTTPS 게이트웨이(8081) 용입니다.

4) Explorer UI 접속(1234)

빌드에 따라 1234는 HTTP 또는 HTTPS 로 열립니다. 아래 순서로 시도하세요.

# 1) HTTPS 먼저 시도
open 'https://localhost:1234/_explorer/index.html'

# 2) 실패 시 HTTP + 127.0.0.1 (HSTS 회피)
open 'http://127.0.0.1:1234/_explorer/index.html'

# 3) 터미널 진단
curl -vk https://localhost:1234/_explorer/index.html | head -n 20
curl -v  http://127.0.0.1:1234/_explorer/index.html | head -n 20

Note: 브라우저가 localhost를 자동으로 HTTPS로 강제하면 Chrome HSTS 정책 삭제 또는 127.0.0.1 주소 사용.

5) VS Code에서 로컬 에뮬레이터 연결(선택)

VS Code 내에서 DB/컨테이너/문서 CRUD 확인 가능.

6) FastAPI + Python SDK 예시

from fastapi import FastAPI
from azure.cosmos import CosmosClient, PartitionKey

COSMOS_URL = "https://localhost:8081"   # 에뮬레이터 게이트웨이(HTTPS)
COSMOS_KEY = "<EMULATOR_KEY>"           # Explorer/확장에서 복사

app = FastAPI()
client = CosmosClient(COSMOS_URL, credential=COSMOS_KEY, connection_verify=True)
db = client.create_database_if_not_exists("demo")
container = db.create_container_if_not_exists(id="items", partition_key=PartitionKey(path="/pk"))

@app.get("/put")
def put_item(id: str, pk: str, **doc):
    item = {"id": id, "pk": pk, **doc}
    container.upsert_item(item)
    return {"ok": True, "id": id, "pk": pk}

@app.get("/get")
def get_item(id: str, pk: str):
    return container.read_item(item=id, partition_key=pk)

Best Practice: 프런트(Vue 등)에서 직접 Cosmos에 연결하지 말고, *백엔드*를 통해 접근(키 노출 방지, 쿼리 통제).

7) 문제 해결(FAQ)

문제

원인

해결

1234 접속 안 됨

Explorer가 HTTP로만 리슨

http://127.0.0.1:1234/_explorer/index.html

로 접속

HTTPS 강제됨

브라우저 HSTS 정책

Chrome HSTS 삭제 또는 127.0.0.1 사용

인증서 임포트 실패

pem 대신 JSON 에러 저장됨

TLS 추출 방식으로 pem 생성 → DER 변환 후 System 키체인에 신뢰 추가

SDK SSL 오류

인증서 미신뢰

System 키체인에서 localhost 인증서 Always Trust 적용 +

https://localhost:8081

사용 확인

8) 클라우드 전환 팁

작성자: Hyounsoo Kim
최종 업데이트: 2025-10-24