Konduo Community를 Docker Compose로 10분 안에 시작하기

Konduo는 여러 운영 대상 시스템을 한 화면 흐름에서 다루기 위한 통합 관리 운영 플랫폼입니다. Redis, PostgreSQL, Kafka, etcd, MySQL, MariaDB 같은 리소스를 플러그인으로 연결하고, 각 리소스의 상태와 메트릭 근거, 대시보드, 알림 대응을 같은 운영 문맥에서 확인할 수 있도록 설계되어 있습니다.

현재 Community에서 제공되는 리소스/운영 플러그인은 Konduo 자체 관찰, Host, Redis, Kafka, PostgreSQL, MySQL/MariaDB, etcd, Keycloak, Prometheus, Milvus, OpenSearch, Synology를 다룹니다. 알림 전달 플러그인으로는 Email, Webhook, Telegram channel을 사용할 수 있습니다. 즉, 단일 시스템 모니터링 도구라기보다 여러 운영 대상을 같은 방식으로 등록하고 관찰하고 대응하기 위한 기반에 가깝습니다.

Konduo Community Edition은 기능을 흉내만 내는 데모 이미지가 아니라, Community 범위의 기능이 실제로 동작하는 제품 버전입니다. 로컬이나 PoC 환경에서도 리소스 등록, 메트릭 소스 연결, 대시보드 확인, 알림 rule과 channel 구성 같은 주요 흐름을 직접 실행해볼 수 있습니다. Docker Hub의 pletorco namespace에 Community frontend, backend, manual 이미지가 공개되어 있으므로, Docker Compose만 있으면 PostgreSQL, Prometheus, 오프라인 매뉴얼까지 포함한 기본 구성을 바로 띄워볼 수 있습니다.

이 글에서는 Docker Compose로 다음 다섯 가지를 함께 올립니다.

Konduo frontend
Konduo backend
Konduo manual, 선택 사항
PostgreSQL
Prometheus

이미 Prometheus를 운영 중인 환경이라면 기존 Prometheus를 연결하면 됩니다. 하지만 처음 제품을 확인하는 독자에게는 Prometheus까지 같이 준비하는 편이 훨씬 쉽습니다. 그래서 이 Quickstart는 Prometheus가 없는 상태를 기준으로 시작합니다.

매뉴얼도 선택 사항입니다. 이 글의 예시는 처음 설치하는 사용자가 제품 화면과 문서를 같은 origin에서 함께 확인할 수 있도록 manual service를 포함합니다. 이미 외부 문서 사이트를 쓰거나 매뉴얼을 별도로 배포하지 않는 환경이라면 manual service를 빼고 KONDUO_MANUAL_URL을 비워 두면 됩니다.

작은 서비스 모듈들이 은은한 빛으로 연결되어 하나의 로컬 시스템으로 켜지는 일러스트 — 몇 개의 컨테이너만 함께 올리면 Konduo Community의 기본 흐름을 로컬에서 바로 확인할 수 있습니다.

브라우저가 Konduo frontend에 접속하고 frontend가 backend와 manual로 연결되며 backend가 PostgreSQL과 Prometheus에 연결되는 Docker Compose 구성도 — Quickstart는 frontend, backend, 선택 사항인 manual, PostgreSQL, Prometheus를 한 Compose 환경에서 함께 실행합니다.

먼저 가져갈 결론

로컬에서 한 번 실행해보는 목적이라면 흐름은 단순합니다.

Docker Hub에서 pletorco/konduo-frontend, pletorco/konduo-backend, pletorco/konduo-manual-ce 이미지를 받습니다.
PostgreSQL을 함께 올려 Konduo 시스템 데이터를 저장합니다.
Prometheus를 함께 올려 backend /metrics를 수집하고 remote write receiver를 활성화합니다.
선택 사항인 매뉴얼 이미지를 함께 올리고 frontend nginx가 /manual/ 경로로 proxy합니다.
브라우저에서 http://localhost:5173에 접속합니다.
admin / admin123!로 첫 로그인 후 즉시 비밀번호를 변경합니다.

이 구성은 로컬 검증, PoC, 빠른 제품 탐색에 적합하지만 단순 화면 데모는 아닙니다. Community Edition의 실제 backend와 frontend가 동작하고, 필요하면 같은 origin의 /manual/ 경로에서 매뉴얼을 열 수 있으며, Prometheus metric source와 resource를 연결해 운영 흐름을 확인할 수 있습니다. Prometheus remote write receiver도 켜두기 때문에 managed metric collect를 사용하는 plugin 흐름까지 이어서 확인할 수 있습니다. 운영 환경에서는 TLS, 백업, 외부 PostgreSQL, 이미지 tag/digest pinning, 비밀값 관리, 네트워크 노출 정책을 별도로 검토해야 합니다.

준비물

필요한 것은 Docker와 Docker Compose입니다.

docker version
docker compose version

이 글의 예시는 Docker Hub public image를 사용합니다.

pletorco/konduo-backend:latest
pletorco/konduo-frontend:latest
pletorco/konduo-manual-ce:latest

2026년 6월 30일 기준 Docker Hub에는 Community backend, frontend, manual CE 이미지의 latest tag가 올라와 있습니다. 빠른 확인에는 latest가 편하지만, 반복 가능한 검증이나 운영 전 테스트에서는 version tag 또는 digest pinning을 권장합니다.

작업 디렉터리 만들기

먼저 작업 디렉터리를 만듭니다.

mkdir -p konduo-quickstart/prometheus
cd konduo-quickstart

이 디렉터리 안에 .env, compose.yml, prometheus/prometheus.yml을 둘 것입니다.

비밀값 준비

KONDUO_SECRET_KEY는 리소스 설정과 인증 정보 같은 저장 비밀을 암호화하는 데 사용됩니다. 한 번 생성한 값은 컨테이너 재시작과 업그레이드 후에도 유지해야 합니다.

openssl rand -hex 32

JWT_SECRET도 별도로 생성합니다.

openssl rand -hex 32

`.env` 작성

.env 파일을 만듭니다.

GO_ENV=development

DB_NAME=konduo
DB_USER=konduo
DB_PASSWORD=change-this-db-password
DB_SSLMODE=disable

JWT_SECRET=change-this-jwt-secret
KONDUO_SECRET_KEY=replace-with-openssl-rand-hex-32
KONDUO_ALERT_INSTANCE_LABEL=QUICKSTART CE
KONDUO_PUBLIC_URL=

BACKEND_IMAGE_REF=pletorco/konduo-backend:latest
FRONTEND_IMAGE_REF=pletorco/konduo-frontend:latest
MANUAL_IMAGE_REF=pletorco/konduo-manual-ce:latest

KONDUO_MANUAL_URL=/manual/
MANUAL_UPSTREAM=manual:8080
MANUAL_PORT=8088

DB_PASSWORD, JWT_SECRET, KONDUO_SECRET_KEY는 그대로 쓰지 말고 직접 생성한 값으로 바꿉니다.

Prometheus 설정 작성

Prometheus가 없다면 Compose stack 안에 함께 올리면 됩니다. Konduo backend는 /metrics endpoint를 노출하므로, Prometheus가 backend service를 scrape하도록 설정합니다.

최근 추가된 일부 plugin의 managed metric collect 기능은 Konduo가 수집한 metric을 Prometheus remote write API로 전달하는 흐름을 사용합니다. 이 기능까지 확인하려면 Prometheus가 remote write receiver로 동작해야 합니다. 이 글의 Compose 예시는 Prometheus 실행 인자에 --web.enable-remote-write-receiver를 포함합니다.

prometheus/prometheus.yml:

global:
  scrape_interval: 15s

scrape_configs:
  - job_name: konduo-backend
    metrics_path: /metrics
    static_configs:
      - targets:
          - backend:8080

이미 Prometheus가 있다면 이 파일 대신 기존 Prometheus에 같은 scrape target을 추가하면 됩니다. Compose 내부 Prometheus에서는 target이 backend:8080이지만, 외부 Prometheus에서는 접근 가능한 host와 port를 기준으로 바꿔야 합니다. Managed metric collect를 사용할 계획이라면 기존 Prometheus도 remote write receiver가 켜져 있어야 합니다.

`compose.yml` 작성

다음 compose.yml은 frontend, backend, 선택 사항인 manual, PostgreSQL, Prometheus를 함께 실행합니다. 매뉴얼이 필요 없다면 manual service와 frontend의 MANUAL_UPSTREAM 설정을 제거하고, .env에서 KONDUO_MANUAL_URL을 빈 값으로 두면 됩니다.

services:
  backend:
    image: ${BACKEND_IMAGE_REF}
    environment:
      GO_ENV: ${GO_ENV:-development}
      PORT: "8080"
      PLUGIN_PACKAGE_DIR: /app/data/plugins
      AUTO_GENERATE_ENV: "true"
      DB_TYPE: postgres
      DB_HOST: postgres
      DB_PORT: "5432"
      DB_NAME: ${DB_NAME:-konduo}
      DB_USER: ${DB_USER:-konduo}
      DB_PASSWORD: ${DB_PASSWORD}
      DB_SSLMODE: ${DB_SSLMODE:-disable}
      JWT_SECRET: ${JWT_SECRET}
      KONDUO_SECRET_KEY: ${KONDUO_SECRET_KEY}
      KONDUO_ALERT_INSTANCE_LABEL: ${KONDUO_ALERT_INSTANCE_LABEL:-}
      KONDUO_PUBLIC_URL: ${KONDUO_PUBLIC_URL:-}
    ports:
      - "8080:8080"
    volumes:
      - konduo_data:/data
    depends_on:
      postgres:
        condition: service_healthy
    restart: unless-stopped

  frontend:
    image: ${FRONTEND_IMAGE_REF}
    environment:
      BACKEND_UPSTREAM: backend:8080
      KONDUO_MANUAL_URL: ${KONDUO_MANUAL_URL-/manual/}
      MANUAL_UPSTREAM: ${MANUAL_UPSTREAM-manual:8080}
      NGINX_PORT: "8080"
    depends_on:
      - backend
    ports:
      - "5173:8080"
    restart: unless-stopped

  manual:
    image: ${MANUAL_IMAGE_REF}
    ports:
      - "${MANUAL_PORT:-8088}:8080"
    restart: unless-stopped

  postgres:
    image: postgres:16-alpine
    shm_size: "256mb"
    environment:
      POSTGRES_DB: ${DB_NAME:-konduo}
      POSTGRES_USER: ${DB_USER:-konduo}
      POSTGRES_PASSWORD: ${DB_PASSWORD}
    ports:
      - "5432:5432"
    volumes:
      - konduo_postgres_data:/var/lib/postgresql/data
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U ${DB_USER:-konduo} -d ${DB_NAME:-konduo}"]
      interval: 10s
      timeout: 5s
      retries: 10
    restart: unless-stopped

  prometheus:
    image: prom/prometheus:v3.5.4
    command:
      - --config.file=/etc/prometheus/prometheus.yml
      - --storage.tsdb.path=/prometheus
      - --web.enable-remote-write-receiver
    volumes:
      - ./prometheus/prometheus.yml:/etc/prometheus/prometheus.yml:ro
      - prometheus_data:/prometheus
    ports:
      - "9090:9090"
    depends_on:
      - backend
    restart: unless-stopped

volumes:
  konduo_data:
  konduo_postgres_data:
  prometheus_data:

실행

이미지를 받고 stack을 시작합니다.

docker compose --env-file .env -f compose.yml pull
docker compose --env-file .env -f compose.yml up -d
docker compose --env-file .env -f compose.yml ps

backend 로그를 확인하려면 다음 명령을 사용합니다.

docker compose --env-file .env -f compose.yml logs -f backend

접속 확인

브라우저에서 frontend를 엽니다.

http://localhost:5173

backend 상태는 다음 명령으로 확인할 수 있습니다.

curl http://localhost:8080/api/v1/system/version
curl http://localhost:8080/metrics

Prometheus는 다음 주소에서 확인합니다.

http://localhost:9090

Prometheus의 Status > Targets에서 konduo-backend target이 UP이면 backend metric 수집이 정상입니다.

매뉴얼을 포함한 경우 frontend nginx를 통해 같은 origin의 /manual/ 경로로 열립니다.

curl -fsS http://localhost:5173/runtime-config.json
curl -fsS http://localhost:5173/manual/manual-build.json

브라우저에서는 다음 주소를 엽니다.

http://localhost:5173/manual/

직접 노출된 manual service 포트로도 확인할 수 있습니다.

http://localhost:8088

UI 언어가 한국어 또는 영어로 설정되어 있으면 상단의 매뉴얼 링크는 해당 언어 경로로 이동합니다. 매뉴얼을 배포하지 않는 구성에서는 .env에 KONDUO_MANUAL_URL=처럼 빈 값을 지정하면 링크가 표시되지 않습니다.

첫 로그인

설치 직후 기본 관리자 계정으로 로그인합니다.

Username: admin
Password: admin123!

로그인 후에는 반드시 관리자 비밀번호를 변경합니다. 기본 비밀번호를 유지한 상태로 외부 네트워크에 노출하면 안 됩니다.

권장 절차는 다음과 같습니다.

http://localhost:5173에 접속합니다.
admin / admin123!로 로그인합니다.
비밀번호 변경 화면이 표시되면 현재 비밀번호에 admin123!를 입력합니다.
새 관리자 비밀번호와 확인 값을 입력합니다.
저장 후 로그아웃합니다.
변경한 비밀번호로 다시 로그인되는지 확인합니다.

다음 단계

Quickstart가 끝나면 이제 Konduo가 실제로 관찰하고 운영할 대상을 연결할 수 있습니다.

Prometheus metric source 등록
Managed metric collect를 쓸 plugin이 있다면 Prometheus remote write receiver 확인
필요하면 매뉴얼에서 설치/운영 절차 확인
Redis, Kafka, PostgreSQL, MySQL/MariaDB, etcd, Keycloak, Milvus, OpenSearch, Synology, Host 같은 resource 추가
dashboard와 alert rule 확인
Email, Webhook, Telegram alert channel 연결
운영 검증용 tag/digest pinning 적용

이때 중요한 점은 Konduo가 단순히 여러 시스템 링크를 모아두는 화면이 아니라는 것입니다. 리소스별 상태, Prometheus 기반 메트릭, 대시보드, 알림 rule, 알림 channel, 운영 권한과 이력을 같은 흐름에서 다루도록 하는 것이 제품의 핵심 방향입니다. Docker Compose Quickstart는 제한된 데모가 아니라, 그 실제 흐름을 가장 작은 구성으로 확인하는 출발점입니다.

정리 체크리스트

마지막으로 다음만 확인하면 됩니다.

pletorco/konduo-backend, pletorco/konduo-frontend 이미지를 사용했는가?
매뉴얼을 포함했다면 pletorco/konduo-manual-ce 이미지를 사용했는가?
KONDUO_SECRET_KEY를 생성하고 안정적으로 보관했는가?
PostgreSQL volume이 유지되는가?
Prometheus target konduo-backend가 UP인가?
Prometheus에 --web.enable-remote-write-receiver가 적용되어 있는가?
매뉴얼을 포함했다면 http://localhost:5173/manual/에서 매뉴얼이 열리는가?
첫 로그인 후 기본 관리자 비밀번호를 바꿨는가?
외부 노출 전에 TLS, 방화벽, 백업, tag pinning을 검토했는가?

Quickstart의 목표는 “완벽한 운영 구성”이 아니라 “제품의 기본 흐름을 빨리 확인하는 것”입니다. 이 경로로 먼저 감을 잡고, 운영 환경에서는 데이터 보존과 보안 경계를 차분히 강화하면 됩니다.

함께 읽기 좋은 글

이 글의 관점과 이어지는 주제를 더 보려면 아래 글도 함께 읽어볼 수 있습니다.

컨테이너 설정 주입의 마지막 한 끗: env에서 config로 - 컨테이너 환경 변수에서 실제 설정 파일을 만드는 패턴을 다룹니다.
Docker Compose는 편한데, .env 비밀값은 너무 쉽게 남는다 - Compose 환경에서 평문 secret 파일을 줄이는 방법을 소개합니다.
JVM 메트릭만으로는 컨테이너를 설명할 수 없다 - JVM 밖의 cgroup, filesystem, fd, I/O 신호를 함께 봐야 하는 이유를 다룹니다.