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(SQLite naru.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을 켤 수 있지만, 사용자가 자기 이메일 속성을 바꿀 수 없을 때만 켜요.

  • 관리자가 아무도 로그인하지 못할 때: 한 시간 동안 한 번 쓸 수 있는 링크를 찍어요.

    bash
    docker 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와 사내 프록시도 돼요.

다음으로

Esc