Naru
설치
Docker Compose로 나루를 띄우고, 앞단에서 TLS를 끝내고, 관리자와 로그인 방식을 정해요.
설치
bash
cp .env.example .env # PUBLIC_URL, SECRETS_KEY(openssl rand -base64 32), 관리자, OIDC
docker compose -f deploy/compose.yaml up -d --build
- TLS는 앞단(사내 L7, nginx, Caddy)에서 끝내고
PUBLIC_URL을 그 https 주소로 둬요. MCP 클라이언트와 OAuth가 이 주소를 그대로 써요. 끝에/를 붙이지 않아요. - 이미지에 Node 24와 JRE 21(sidecar)이 들어 있어요. 컨테이너는 읽기 전용 루트,
cap_drop: ALL로 돌 수 있어요. - 데이터는
/data(SQLitenaru.sqlite, pack 번들)에 있어요.DATABASE_URL로 PostgreSQL을 고를 수 있고, 그래도 pack과 파일은/data에 남아요. 앱은 한 인스턴스로 운영해요.
관리자와 로그인
-
관리자:
ADMIN_EMAILS(쉼표로 여러 개)의 사람을 시작할 때 관리자로 만들어요. 비우면 로그에 찍히는/setup?token=…주소로 첫 관리자를 정해요. -
로그인 방식(
LOGIN_METHODS):email(이메일 코드만),oidc(사내 계정만),email,oidc. 비워 두면 이메일 코드,OIDC_ISSUER가 있으면 사내 계정도 함께 보여요. -
이메일 코드: 6자리 코드(10분, 한 번, 5번 틀리면 무효)나 같은 메일의 링크예요.
SMTP_URL,MAIL_FROM이 없으면 코드가 서버 로그에 남아요. -
사내 계정(OIDC):
OIDC_ISSUER,OIDC_CLIENT_ID,OIDC_CLIENT_SECRET. IdP가email_verified: true라고 알려 줄 때만 같은 이메일의 계정에 잇거나 새로 만들어요. ADFS·Entra ID처럼 이 claim을 보내지 않는 IdP는OIDC_ASSUME_EMAIL_VERIFIED=1을 켤 수 있지만, 사용자가 자기 이메일 속성을 바꿀 수 없을 때만 켜요. -
관리자가 아무도 로그인하지 못할 때: 한 시간 동안 한 번 쓸 수 있는 링크를 찍어요.
bashdocker compose -f deploy/compose.yaml exec naru naru-recover you@example.com
상태 확인
| 주소 | 확인하는 것 |
|---|---|
/healthz, /healthz/live |
프로세스가 살아 있는지 |
/healthz/ready |
DB가 답하는지까지(안 되면 503). 부하 분산기와 readiness에 써요 |
네트워크
- 나루가 나가는 주소(컨테이너 호스트의 IP)를 레거시 시스템의 허용 목록과 방화벽에 등록해요.
- 사설 대역은 연결할 수 있어요. link-local·클라우드 메타데이터·멀티캐스트는 늘 막혀요. loopback은
NARU_ALLOW_LOOPBACK=1(개발 전용)일 때만이에요. - 시스템 TLS는
verify(공인 CA, 사내 CA는ca에 PEM),pinned(공개키sha256//…),insecure(개발 전용)예요. mTLS와 사내 프록시도 돼요.
다음으로
설치 방법 · 나루 설치 · 배포