MQTT Broker Setup Guide

# macOS 환경인 경우 Homebrew로 설치
brew install mosquitto

# Debian / Ubuntu 리눅스 환경인 경우
sudo apt-get update && sudo apt-get install -y mosquitto mosquitto-clients

# Docker 컨테이너 가상 머신으로 가동하는 경우
docker run -d --name mosquitto -p 8883:8883 \
  -v "$PWD/mosquitto.conf:/mosquitto/config/mosquitto.conf" \
  -v "$PWD/certs:/mosquitto/certs" \
  -v "$PWD/auth:/mosquitto/auth" \
  eclipse-mosquitto:2

persistence true
persistence_location /mosquitto/data/

password_file /mosquitto/auth/passwd
acl_file      /mosquitto/auth/acl
allow_anonymous false

listener 8883
cafile   /mosquitto/certs/ca.crt
certfile /mosquitto/certs/server.crt
keyfile  /mosquitto/certs/server.key

# 최초 사용자(hermes) 등록 (-c 옵션은 기존 파일 초기화 및 재생성하므로 최초 1회만 사용)
mosquitto_passwd -c /mosquitto/auth/passwd hermes

# 추가 에이전트 전용 계정 등록 (-c를 붙이면 기존 패스워드 목록이 휘발되므로 제외)
mosquitto_passwd /mosquitto/auth/passwd claude-worker

mkdir -p certs && cd certs
openssl req -x509 -newkey rsa:2048 -nodes -days 825 \
  -keyout server.key -out server.crt \
  -subj "/CN=mqtt.internal"
cp server.crt ca.crt   # 클라이언트는 동일 인증서를 루트 CA 신뢰용 인증서로 복사하여 참조

# 1) 사내 최상위 루트 CA 키 및 인증서 생성 (10년 보존 기한)
openssl genrsa -out ca.key 4096
openssl req -x509 -new -nodes -key ca.key -days 3650 -out ca.crt -subj "/CN=Hermes-CA"

# 2) 브로커용 개인키 및 CSR 발급 신청 파일 생성
openssl genrsa -out server.key 2048
openssl req -new -key server.key -out server.csr -subj "/CN=mqtt.internal"

# 3) 루트 CA 개인키 서명을 통해 최종 브로커용 인증서 생성 (825일 유효)
openssl x509 -req -in server.csr -CA ca.crt -CAkey ca.key -CAcreateserial \
  -out server.crt -days 825

# claude-worker: 지정한 JID의 하위 이벤트 토픽에 메시지를 '발행'할 권한만 소유
user claude-worker
topic write python/mqtt/jobs/+/events

# hermes: 모든 작업 식별자 토픽으로부터 이벤트를 '구독'할 권한만 소유
user hermes
topic read python/mqtt/jobs/+/events

# 호환성 검증용 샘플 토픽 권한 공유
pattern readwrite python/mqtt/sample

# 1) 쉘 환경에 신규 브로커 접속 매개변수 바인딩
export MQTT_BROKER=mqtt.internal
export MQTT_PORT=8883
export MQTT_TLS=1
export MQTT_CA_CERTS=$PWD/certs/ca.crt
export MQTT_USERNAME=hermes
export MQTT_PASSWORD=secure_hermes_password

# 2) mosquitto CLI 유틸리티를 활용한 선 구독 점검
mosquitto_sub -h "$MQTT_BROKER" -p 8883 --cafile "$MQTT_CA_CERTS" \
  -u hermes -P "$MQTT_PASSWORD" -t 'python/mqtt/jobs/+/events' -v &

# 3) 작업 위임 스크립트를 변경 없이 실행
PY=.venv/bin/python
JID=$($PY scripts/registry.py register --prompt "broker cutover smoke test")
$PY scripts/job_subscriber.py --job "$JID" --timeout 30 &
sleep 3
$PY scripts/publish_event.py --job "$JID" --event started
$PY scripts/publish_event.py --job "$JID" --event completed

"broker": {
  "host": "mqtt.internal",
  "port": 8883,
  "tls": true,
  "username": "claude-worker",
  "password": "…"
}