2.2. 설치 — 일반 Linux 호스트 설치형
OPENMARU Observability를 일반 Linux 호스트에 Docker Compose로 설치하는 방법을 안내합니다.
개요
OPENMARU Observability는 Kubernetes 없이 일반 Linux 호스트에서 동작합니다. 서버 스택은 Docker Compose로 한 번에 기동하고, 모니터링할 각 호스트에는 노드 에이전트(Node Agent)를 배포합니다.
설치가 끝나면 노드 에이전트가 각 호스트에서 메트릭(Metric), 로그(Log), 추적(Trace), 프로파일링(Profiling) 데이터를 수집해 서버로 보냅니다. 애플리케이션 코드를 고치거나 별도 SDK를 설치할 필요가 없습니다.
이 장은 설치를 마치고 화면을 보기까지의 최단 경로를 다룹니다. 인터넷이 차단된 환경의 Docker 오프라인 설치, 환경변수 전체 목록, 언어별 OpenTelemetry 계측 등 자세한 내용은 설치·운영 매뉴얼을 참고하세요.
구성 요소
서버 호스트 1대에 아래 서비스가 컨테이너로 함께 뜹니다.
| 구성 요소 | 역할 | 외부 포트 |
|---|---|---|
| 서버 | 수집한 데이터를 처리하고 UI에 제공합니다 | 8080 |
| UI | 브라우저로 접근하는 웹 화면입니다 | 80 |
| Keycloak | 로그인(SSO)을 담당합니다 | 8081 |
| OTel Collector | OpenTelemetry 데이터를 받는 수집기입니다 | 4317, 4318 |
| PostgreSQL | 설정과 사용자 정보를 저장합니다 | 내부 전용 |
| ClickHouse | 로그·추적·프로파일링 데이터를 저장합니다 | 내부 전용 |
| VictoriaMetrics | 메트릭을 저장하는 시계열 데이터베이스입니다 | 내부 전용 |
| 클러스터 에이전트(Cluster Agent) | 데이터베이스·AWS RDS 계측 메트 릭을 수집합니다 | 내부 전용 |
노드 에이전트는 이 스택에 포함되지 않습니다. 모니터링할 호스트마다 따로 배포합니다.
데이터 흐름
노드 에이전트가 서버로 데이터를 보내는(푸시) 방식이라, 모니터링 대상 호스트가 여러 곳에 흩어져 있어도 서버에서 각 호스트로 접속할 필요가 없습니다.
시스템 요구사항
서버 호스트
| 항목 | 요구사항 |
|---|---|
| OS | 일반 Linux (x86_64 또는 ARM64), 서버 1대 |
| 런타임 | Docker와 docker compose v2 |
| 메모리 | 16 GB 이상 권장 — 컨테이너에 걸린 제한 합계가 약 13 GB입니다 |
| CPU | 16 vCPU 이상 권장 — 컨테이너에 걸린 제한 합계가 약 8 vCPU입니다 |
| 디스크 | 배포 디렉터리의 data/에 쌓입니다. 로그·추적(ClickHouse) 보존량에 비례합니다 |
| 실행 권한 | root로 실행해야 합니다 |
| SELinux | Enforcing이면 데이터 디렉터리 접근이 막힙니다 |
root 실행이 필요한 이유: 기동 스크립트가
data/아래 디렉터리를 각 컨테이너의 실행 계정으로 넘겨줍니다(chown). root가 아니면 이 단계가 건너뛰어져 컨테이너가 데이터 디렉터리에 쓰지 못하고 반복해서 종료됩니다.
SELinux: Enforcing 상태면
setenforce 0으로 끄고/etc/selinux/config에서SELINUX=disabled로 둡니다. 끄지 않으려면 Compose 볼륨에:z라벨을 붙여야 합니다.
노드 에이전트를 설치할 호스트
노드 에이전트는 eBPF로 호스트 커널에서 데이터를 수집합니다. 아래 요건은 컨테이너가 아니라 호스트 운영체제 기준입니다.
| 항목 | 요구사항 |
|---|---|
| 커널 | Linux 커널 4.16 이상 — 기동할 때 검사하며 미달이면 시작하지 않습니다 |
| RHEL 계열 | RHEL 8 이상. RHEL·CentOS·Rocky·Alma 7은 커널 3.10이라 지원하지 않습니다 |
| tracefs | /sys/kernel/debug/tracing 또는 /sys/kernel/tracing이 있어야 합니다 |
| 네트워크 | 서 버의 수집 포트(기본 8080)에 도달할 수 있어야 합니다 |
| 배포 단위 | 모니터링할 호스트마다 1개 |
포트
| 포트 | 용도 |
|---|---|
| 80 | UI 접속 |
| 8080 | 노드 에이전트가 데이터를 보내는 수집 포트 |
| 8081 | Keycloak 관리 화면 |
| 4317, 4318 | OpenTelemetry 데이터 수신 |
참고: 같은 호스트에서 8080 포트를 이미 쓰고 있으면
.env의SERVER_HTTP_PORT를 바꿉니다. 이때 노드 에이전트가 가리키는 주소도 같은 포트로 맞춰야 합니다.
서버 스택 설치
배포 디렉터리(observ-server/)를 서버 호스트에 복사한 뒤 root로 실행합니다.
cd observ-server
# 1) 기동 — 서버 호스트의 IP를 주면 .env 를 만들면서 접속 주소에 넣습니다.
OBSERV_HOST=10.20.10.5 ./start-observ.sh
# 2) 점검 — 서버가 정상 상태가 될 때까지 기다렸다가 접속 주소를 보여줍니다.
./verify-observ.sh
start-observ.sh가 하는 일은 다음과 같습니다.
.env가 없으면 만들고, 로그인에 쓰는 비밀값을 무작위로 발급합니다.data/아래 디렉터리를 만들고 각 컨테이너의 실행 계정으로 넘깁니다..env에CHANGE-ME가 남아 있으면 오류를 내고 멈춥니다.- 로그인(Keycloak) 설정을 만들고 전체 서비스를 기동합니다.
.env는 처음 한 번만 만들어집니다. 값을 다시 잡으려면.env를 지우고 다시 실행합니다.OBSERV_HOST를 주지 않으면 호스트의 첫 IP를 자동으로 찾아 씁니다.
주요 설정 항목
설정은 .env 파일 한 곳에 있습니다.
| 변수 | 기본값 | 설명 |
|---|---|---|
UI_HTTP_PORT | 80 | UI 접속 포트 |
SERVER_HTTP_PORT | 8080 | 노드 에이전트가 접속하는 수집 포트 |
KC_HTTP_PORT | 8081 | Keycloak 관리 화면 포트 |
POSTGRES_PASSWORD | openmaru1234 | 설정 데이터베이스 비밀번호 |
CLICKHOUSE_PASSWORD | 27MefVmNE3 | ClickHouse 비밀번호 |
OPENMARU_OBSERV_API_KEY | bm56xxcb | 에이전트·OpenTelemetry 인증에 쓰는 프로젝트 키 |
SERVER_SECURE_COOKIE | false | HTTP로 서비스하면 false여야 합니다. HTTPS 프록시 뒤에 두면 true |
주의: 운영 환경에서는 기본 비밀번호를 반드시 바꿉니다. 비밀번호는
.env한 곳만 고치면 서버와 데이터베이스 양쪽에 함께 적용됩니다.
관리 명령
| 명령 | 하는 일 |
|---|---|
./start-observ.sh | 전체 기동 |
./stop-observ.sh | 전체 중지 (데 이터는 보존) |
./status-observ.sh | 서비스 상태 확인 |
./tail-observ.sh | 전체 로그 확인 |
./verify-observ.sh | 서버가 정상인지 점검 |
./start-observ-one.sh <서비스> | 서비스 하나만 재기동 (stop·tail도 같은 형식) |
서비스 이름: postgres clickhouse victoria-metrics server ui otel-collector
cluster-agent keycloak
노드 에이전트 설치
서버만 띄우면 화면에 데이터가 없습니다. 모니터링할 호스트마다 노드 에이전트를 배포합니다.
배포 디렉터리(observ-node-agent/)를 대상 호스트에 복사한 뒤:
cd observ-node-agent
# 서버 호스트 주소만 주면 나머지는 자동 으로 구성됩니다.
COLLECTOR_HOST=10.20.10.5 ./start-node-agent.sh
# 점검
./verify-node-agent.sh
COLLECTOR_HOST에는 서버 호스트의 IP 주소를 넣습니다. 서버에서 SERVER_HTTP_PORT를
기본값에서 바꿨다면 에이전트가 보는 주소도 같은 포트로 맞춥니다.
모니터링할 호스트가 여러 대면 각 호스트에서 같은 절차를 반복합니다.
노드 에이전트는 호스트 커널에서 동작해야 하므로 컨테이너를
privileged권한으로 띄웁니다. 신뢰할 수 있는 이미지만 사용하세요.
설치 확인
# 1) 전체 서비스가 떠 있는지
./status-observ.sh
# 2) 서버 상태
curl http://localhost:8080/health
# 3) 노드 에이전트가 보낸 메트릭이 쌓이는지
curl 'http://127.0.0.1:8428/api/v1/query?query=up'
브라우저에서 http://<서버 호스트>/ 로 접속해 로그인하면 설치가 끝난 것입니다.
기본 계정
| 대상 | 주소 | 아이디 | 비밀번호 |
|---|---|---|---|
| UI | http://<서버 호스트>/ | omadm | openmaru12#$ |
| Keycloak 관리 화면 | http://<서버 호스트>:8081/ | omadm | openmaru12#$ |
두 계정은 아이디가 같지만 서로 다른 영역(realm)의 별개 계정입니다. UI 사용자를 추가·변경할
때는 Keycloak 관리 화면의 openmaru 영역에서 합니다.
주의: 두 계정 모두 운영 환경에서는 반드시 비밀번호를 바꿉니다.
인터넷이 차단된 환경
이미지를 내려받을 수 없는 환경에서는 이미지 묶음을 파일로 옮겨 설치합니다.
# 배포 디렉터리에 images/ 를 복원한 뒤
./docker-load-image.sh # 호스트 아키텍처를 판정해 이미지를 등록합니다
./start-observ.sh
노드 에이전트 배포 디렉터리에도 같은 이름의 스크립트가 있습니다. 호스트에 Docker 자체가 없는 경우의 오프라인 설치 절차는 설치·운영 매뉴얼을 참고하세요.
업그레이드
docker compose pull && ./start-observ.sh
./verify-observ.sh
인터넷이 차단된 환경은 새 이미지 묶음을 반입해 ./docker-load-image.sh 를 실행한 뒤 기동합니다.
데이터는 배포 디렉터리 아래 data/에 남아 있어 그대로 이어집니다.
삭제
./stop-observ.sh
데이터까지 지우려면 중지한 뒤 배포 디렉터리의 data/를 삭제합니다. 지우면 되돌릴 수 없으므로
필요한 데이터는 먼저 백업합니다. 설정 데이터베이스는 아래 명령으로 백업합니다.
docker compose exec postgres pg_dump -U "$POSTGRES_USER" openmaru-observ > pg-backup.sql
문제 해결
| 증상 | 원인과 조치 |
|---|---|
CHANGE-ME 오류로 기동이 멈춤 | .env에 바꾸지 않은 값이 남아 있습니다. 해당 줄을 운영값으로 바꿉니다 |
| 컨테이 너가 권한 오류로 반복 종료됨 | root로 실행하지 않았거나 SELinux가 Enforcing입니다. 「시스템 요구사항」 참고 |
| 서버가 반복해서 재시작됨 | .env의 데이터베이스 비밀번호가 서로 맞지 않습니다. ./tail-observ.sh server 로 확인 |
| UI·수집기가 뜨지 않음 | 서버가 정상이 될 때까지 기다리는 중입니다. 서버 로그를 먼저 확인합니다 |
| 화면은 뜨는데 차트가 비어 있음 | 노드 에이전트가 배포됐는지, 서버 주소를 맞게 가리키는지 확인합니다 |
| 노드가 목록에 안 보임 | 대상 호스트에서 ./verify-node-agent.sh 실행. 서버 수집 포트에 도달하는지 확인 |
| 로그인 화면이 깨짐 | Keycloak 로그인 테마 파일이 배포 디렉터리에 있어야 합니다 |
더 자세한 진단은 문제 해결 장과 설치·운영 매뉴얼을 참고하세요.