목적: 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) 사전 준비
- Docker Desktop for Mac (Apple Silicon)
- VS Code
- (선택) VS Code Azure Cosmos DB 확장
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 → Azure Cosmos DB 확장 설치
- Local Emulator 연결 추가
- Endpoint: https://localhost:8081

- Key: 에뮬레이터 기본 키(Explorer UI/확장에서 확인 가능)
- Endpoint: https://localhost:8081
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) 클라우드 전환 팁
- 로컬 검증 완료 후 Azure Cosmos DB *Free Tier*로 계정 생성 → 연결 문자열 교체만으로 대부분 호환.
- 성능은 RU/s, 인덱싱 정책 튜닝에 집중.
...
작성자: Hyounsoo Kim
최종 업데이트: 2025-10-24