첫 부팅 체크리스트

install.sh 가 끝나고 부트스트랩 관리자로 로그인한 직후 이 목록을 훑으세요. 어느 것도 "무언가를 보기" 위해 필수는 아닙니다 — Quickstart 는 이것들 없이도 동작합니다 — 그러나 각 항목은 시스템을 팀에 넘기기 전에 빈틈을 메꿉니다.

1. ONGRID_PUBLIC_URL 을 정확히 설정

아마도 가장 중요한 항목입니다. 이 URL 은 edge 들이 데이터 플레인 에 사용하는 것입니다 — 로그는 <url>/loki/api/v1/push 로, 트레이스는 <url>/v1/traces 로 push.

install.sh 가 채운 값을 확인하세요.

sudo grep '^ONGRID_PUBLIC_URL=' /opt/ongrid/.env

내부 주소를 수락했는데 edge 가 공인 인터넷에 있다면 로그와 트레이스가 조용히 실패 — 터널은 (자체 포트로) 여전히 동작하므로 edge 는 정상으로 보입니다.

수정:

# Edit
sudo sed -i 's|^ONGRID_PUBLIC_URL=.*|ONGRID_PUBLIC_URL=https://ops.example.com|' /opt/ongrid/.env

# Restart the affected services
sudo docker compose -f /opt/ongrid/docker-compose.yml --env-file /opt/ongrid/.env up -d ongrid nginx

edge 재배포는 필요 없습니다. 에이전트가 주기적으로 매니저에서 데이터 플레인 엔드포인트를 재독합니다.

ONGRID_PUBLIC_URL 참고.

2. 기본 LLM provider 구성

기본적으로 provider 가 구성되어 있지 않습니다. 에이전트가 사고를 거부합니다.

1. Settings → Models. 다음 중 하나 선택:
   • OpenAI (gpt-5.4 기본)
   • Anthropic (claude-opus-4-7 기본)
   • Zhipu (glm-4.7 기본)
   • DeepSeek (deepseek-v4-flash 기본)
   • Gemini (gemini-2.5-pro 기본)
   • Kimi (kimi-k2.6 기본)
   • Custom OpenAI-compatible (vLLM, Ollama, OpenRouter, 사내 relay…)
2. API 키 붙여넣기. 선택: "Advanced" 에서 기본 모델 오버라이드.
3. Save. Pre-registration 은 hot — 재시작 없음.
4. 같은 페이지에서 Default provider 를 방금 배선한 것으로 설정.

default_provider 와 라우트별 모델을 혼동하지 말 것

"default" 는 백엔드 LLM 호출 (알림 investigation, 번역, 요약) 을 구동합니다. 채팅 헤더의 모델 선택기는 스레드별 오버라이드 입니다 — "이 질문 하나에만 Opus 시도" 에는 유용하지만 cron 작업과 incident 에 실행되는 것은 사이트 기본입니다.

사이드바의 Models 아래 Routing & default 와 Budget & limits 항목을 참고하세요.

3. 알림 채널 구성

아직 알림 규칙이 없더라도 향후 incident 가 도착할 곳이 있도록 채널 하나는 배선해 두세요.

권장 스타터 페어:

• Webhook channel — 일반 incoming-webhook 수집기로 (나중에 제거 가능) — 알림 경로가 동작함을 입증.
• 하나의 IM channel — Telegram 이 가장 쉽습니다 (봇 토큰과 chat ID 만 필요). Slack/Lark/DingTalk/WeCom 은 설정이 더 많습니다.

채널 개요 참고.

4. 매니저 시간대 설정

incident 타임라인과 알림 이벤트의 타임스탬프는 매니저의 시간대를 따릅니다. 컨테이너 내부 기본은 UTC; 팀과 맞추려면:

# compose env 에 TZ 설정. /opt/ongrid/docker-compose.yml 편집 또는 다음을 담은
# /opt/ongrid/docker-compose.override.yml 작성:
services:
  ongrid:
    environment:
      TZ: Asia/Seoul

sudo docker compose -f /opt/ongrid/docker-compose.yml --env-file /opt/ongrid/.env up -d ongrid

AI 출력 로케일 (LLM 이 영어 또는 한국어로 답하는지) 은 ONGRID_DEFAULT_LOCALE 로 설정. 기본 en; 유효 값은 UI 번역 (en, zh-CN, ja, …) 과 일치. 채널은 채널별로 오버라이드 가능; 수동 UI 요청은 Accept-Language 를 따릅니다.

5. Prometheus 보존 결정

compose 의 기본은 90 일 / 20 GB 상한. 변경:

# /opt/ongrid/docker-compose.override.yml
services:
  prometheus:
    command:
      - --storage.tsdb.path=/prometheus
      - --storage.tsdb.retention.time=30d
      - --storage.tsdb.retention.size=10GB
      - --web.enable-remote-write-receiver
      - --web.enable-lifecycle
      - --web.external-url=/prometheus/
      - --web.route-prefix=/prometheus/
      - --config.file=/etc/prometheus/prometheus.yml

sudo docker compose -f /opt/ongrid/docker-compose.yml --env-file /opt/ongrid/.env up -d prometheus

Loki 보존은 /opt/ongrid/loki-config.yaml 편집 후 loki 컨테이너 재시작. Tempo 는 /opt/ongrid/tempo-config.yaml 편집.

6. 내장 Loki / Tempo 유지 여부 결정

이미 매니지드 로그/트레이스 백엔드 (Grafana Cloud, Honeycomb, Splunk, 자체 VictoriaLogs / VictoriaTraces…) 를 운영한다면:

• 내장본 유지 — 에이전트가 쿼리할 데이터 싱크로 (가장 저렴, 추가 인프라 없음).
• 교체 — 에이전트를 매니지드 URL 로 가리키도록 ONGRID_LOG_QUERY_URL / ONGRID_TRACE_QUERY_URL 설정, 각 edge 의 promtail / otelcol 을 직접 거기로 push 하도록 재구성.

하이브리드 설정 (edge 가 둘 다에 push) 의 경우 각 edge 의 /etc/ongrid-edge/ 에 커스텀 promtail.yaml / otelcol.yaml 을 두면 에이전트가 픽업합니다.

로그 기능 와 트레이스 기능 참고.

7. self-signed TLS 인증서 교체

시험 사용에는 괜찮습니다. prod 에서는 인증서가 /opt/ongrid/certs/ 에 있습니다.

sudo cp fullchain.pem /opt/ongrid/certs/tls.crt
sudo cp privkey.pem   /opt/ongrid/certs/tls.key
sudo chmod 600        /opt/ongrid/certs/tls.key
sudo chmod 644        /opt/ongrid/certs/tls.crt
sudo docker compose -f /opt/ongrid/docker-compose.yml restart nginx

install.sh 와 upgrade.sh 는 운영자 인증서를 절대 덮어쓰지 않습니다.

8. /var/lib/ongrid 와 /opt/ongrid/.env 백업

모든 상태 저장 데이터는 두 경로 아래에 있습니다.

• /opt/ongrid/.env — 시크릿 (JWT, MySQL, 관리자 비밀번호, embed 키).
• /var/lib/ongrid/mysql/ — 모든 운영 상태. 잃을 수 없는 모든 것이 여기에 삽니다: edges, 알림 규칙, incidents, 채널 설정, 감사 로그, 커스텀 기능, 지식 메타데이터.
• /var/lib/ongrid/qdrant/ — 벡터 임베딩 (소스 문서로부터 재구축 가능하지만 비쌈).
• /var/lib/ongrid/prometheus/, loki/, tempo/ — 텔레메트리; 긴 보존이 필요하면 백업.

간단한 cron + rsync (또는 restic) 로 이 두 루트를 백업하면 재해 복구가 됩니다. 복원 = 스택 중지, 디렉터리 교체, 스택 시작.

9. 실제 관리자 계정 설정

부트스트랩 관리자의 이메일은 ONGRID_ADMIN_EMAIL 에 넣은 값입니다. 실제 팀을 위해서는:

1. Settings → Identity → Users → Invite user 로 각 실제 운영자 초대.
2. 각 사용자에게 역할 할당: admin, user, viewer (ADR-022 RBAC).
   • admin — 전체 제어.
   • user — 에이전트와 채팅, incident 확인, 알림 음소거 가능. Toolbag 은 ClassSafe 로 필터링.
   • viewer — 읽기 전용 채팅 (쓰기 기능 없음), 읽기 전용 incident.
3. 원하면 부트스트랩 관리자를 강등하거나 사용을 중단.

10. 첫 incident 트리거 (스모크 테스트)

내장 규칙 중 하나를 강제로 발화시킵니다. 가장 간단: edge 중 하나를 중지.

sudo systemctl stop ongrid-edge

ONGRID_ALERT_EDGE_OFFLINE_THRESHOLD (기본 90 초) + evaluator 간격 (기본 5 분) 내에 edge_offline 규칙이 발화합니다. UI:

• Alerts — 새 이벤트.
• Incidents — 그 이벤트를 그룹화한 새 incident.
• Channels — 배선된 채널이 카드를 수신.

IM 채널을 설정했다면 봇에게 "investigate this" 라고 답장하세요. incident investigator 가 끝까지 실행되어 보고서를 게시합니다.

edge 재시작:

sudo systemctl start ongrid-edge

규칙이 발화하지 않으면 incident 가 자동으로 mitigated 로 이동. UI 에서 resolved 로 표시합니다.

다음은

• 채널 개요 — 실제 온콜 채널 배선.
• 알림 기능 — 6 개 내장 외에 커스텀 규칙 작성.
• Upgrade — v0.7.X+1 릴리스 시.
• Reference / env — 모든 ONGRID_* 튜너블.