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 프런트엔드에 접속하고, 백엔드는 PostgreSQL을 사용하며 직접 수집한 메트릭을 Prometheus에 기록하는 Docker Compose 구성도 — Quick Start는 프런트엔드, 백엔드, 선택 사항인 매뉴얼, PostgreSQL, Prometheus를 함께 실행하고 직접 수집한 메트릭을 Prometheus에 저장합니다.

먼저 가져갈 결론

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

Docker Hub에서 pletorco/konduo-frontend, pletorco/konduo-backend, pletorco/konduo-manual-ce 이미지를 받습니다.
PostgreSQL을 함께 올려 Konduo 시스템 데이터를 저장합니다.
Prometheus를 메트릭 저장·조회 계층으로 함께 올리고 remote write receiver를 활성화합니다.
선택 사항인 매뉴얼 이미지를 함께 올리고 프런트엔드의 Caddy가 /manual/ 경로로 프록시합니다.
서버 터미널에서 최초 관리자 계정을 생성합니다.
브라우저에서 http://localhost:5173에 접속합니다.
생성한 관리자 계정으로 처음 로그인하고 비밀번호를 변경합니다.
자동 등록된 Konduo와 PostgreSQL 리소스를 확인합니다.
Prometheus 메트릭 소스를 등록해 두 리소스에 연결하고 대시보드의 메트릭을 확인합니다.

이 구성은 로컬 검증, PoC, 빠른 제품 탐색에 적합하지만 단순 화면 데모는 아닙니다. Community Edition의 실제 백엔드와 프런트엔드가 동작하며, 새 데이터베이스로 처음 실행하면 Konduo 자체 리소스와 주 데이터베이스인 PostgreSQL 리소스가 자동으로 등록됩니다. Prometheus 메트릭 소스만 등록해 연결하면 Konduo가 두 리소스의 메트릭을 직접 수집하고 Prometheus에 기록하는 흐름까지 확인할 수 있습니다. 운영 환경에서는 TLS, 백업, 외부 PostgreSQL, 이미지 태그나 digest 고정, 비밀값 관리, 네트워크 노출 정책을 별도로 검토해야 합니다.

준비물

필요한 것은 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 구성 안에 함께 올리면 됩니다. 이 Quick Start에서 Prometheus는 Konduo가 직접 수집한 메트릭을 저장하고 조회하는 계층입니다. PostgreSQL과 Konduo 자체 리소스는 별도의 exporter를 Prometheus 수집 대상으로 등록하는 대신, Konduo가 메트릭을 수집해 Prometheus remote write API로 보냅니다.

따라서 기본 prometheus.yml에는 수집 대상을 추가하지 않아도 됩니다. 대신 Prometheus가 remote write 요청을 받을 수 있도록 실행 인자에 --web.enable-remote-write-receiver를 지정해야 합니다. 아래 Compose 예제에 이 인자가 포함되어 있습니다.

prometheus/prometheus.yml:

global:
  scrape_interval: 15s

scrape_configs: []

비어 있는 scrape_configs는 의도된 설정입니다. 이 실습의 PostgreSQL과 Konduo 메트릭은 Konduo가 직접 수집하므로 Prometheus에 두 시스템을 별도 수집 대상으로 등록할 필요가 없습니다. 다른 시스템의 exporter를 Prometheus가 직접 수집하는 구성을 추가할 때만 해당 작업을 정의하면 됩니다.

이미 Prometheus를 운영 중이라면 Compose의 Prometheus 서비스를 생략하고 기존 서버를 메트릭 소스로 연결할 수 있습니다. 이 경우에도 Konduo 백엔드가 Prometheus의 조회 API와 remote write API에 접근할 수 있어야 하며, 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}
      KONDUO_FRONTEND_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:

현재 프런트엔드 이미지는 웹 서버로 Caddy를 사용합니다. 컨테이너 내부 수신 포트는 KONDUO_FRONTEND_PORT로 지정하며, 이전 이미지에서 사용하던 NGINX_PORT는 더 이상 지원하지 않습니다. 위 예제는 호스트의 5173 포트를 컨테이너의 8080 포트에 연결하므로 브라우저에서는 계속 http://localhost:5173으로 접속합니다.

실행

이미지를 받고 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가 요청을 받을 준비가 되었는지는 다음 명령으로 확인합니다.

curl -fsS http://localhost:9090/-/ready

이 예제에서는 Prometheus의 Status > Targets가 비어 있어도 정상입니다. PostgreSQL과 Konduo 자체 메트릭은 Prometheus가 직접 가져가는 방식이 아니라 Konduo가 수집해 remote write로 보내기 때문입니다.

매뉴얼을 포함한 경우 프런트엔드의 Caddy를 통해 같은 출처의 /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=처럼 빈 값을 지정하면 링크가 표시되지 않습니다.

최초 관리자 생성과 첫 로그인

새로 설치한 Konduo는 관리자 계정이나 기본 비밀번호를 자동으로 만들지 않습니다. 브라우저를 열기 전에 Compose를 실행한 서버에서 최초 관리자를 생성합니다.

compose.yml과 .env가 있는 디렉터리에서 Bash 터미널을 열고 현재 상태를 확인합니다. 이 명령은 브라우저나 컨테이너 내부 셸이 아니라 서버 터미널에서 실행해야 하며, 백엔드와 PostgreSQL이 먼저 실행 중이어야 합니다.

docker compose --env-file .env -f compose.yml exec -T backend \
  /app/konduo-backend admin-bootstrap-status

상태가 setup_required라면 최초 관리자를 생성합니다. 다음 예시는 사용자 이름으로 admin을 사용하지만, 다른 이름을 쓰려면 --username 값을 바꾸면 됩니다. 비밀번호는 화면에 표시되지 않으며 표준 입력으로 컨테이너에 전달됩니다.

read -rsp '초기 관리자 비밀번호: ' INITIAL_ADMIN_PASSWORD
echo
printf '%s\n' "$INITIAL_ADMIN_PASSWORD" |
  docker compose --env-file .env -f compose.yml exec -T backend \
    /app/konduo-backend admin-bootstrap --username admin --password-stdin
unset INITIAL_ADMIN_PASSWORD

비밀번호는 현재 인증 정책을 만족해야 합니다. INITIAL_ADMIN_PASSWORD는 위 명령을 실행하는 동안만 사용하는 셸 변수입니다. .env에 같은 이름의 값을 추가해도 관리자 계정은 생성되지 않습니다.

생성 명령을 마치면 admin-bootstrap-status를 다시 실행해 상태가 complete인지 확인합니다. 이미 complete라면 기존 관리자 계정을 사용해야 하며, 생성 명령을 다시 실행해도 기존 비밀번호는 바뀌지 않습니다. recovery_required는 최초 설정이 끝났지만 활성 관리자가 없다는 뜻이므로, 데이터베이스를 초기화하거나 최초 생성 명령으로 덮어쓰지 말고 운영 환경의 계정 복구 절차를 따라야 합니다.

이제 다음 순서로 로그인합니다.

http://localhost:5173에 접속합니다.
앞에서 생성한 사용자 이름과 초기 비밀번호로 로그인합니다.
최초 비밀번호 변경 화면에서 초기 비밀번호를 현재 비밀번호로 입력합니다.
새 관리자 비밀번호와 확인 값을 입력합니다.
저장 후 로그아웃합니다.
변경한 비밀번호로 다시 로그인되는지 확인합니다.

최초 관리자 생성과 비밀번호 변경을 마치기 전에는 서비스를 외부 사용자에게 개방하지 마세요. 생성 전에는 백엔드 준비 상태 검사(/readyz)가 실패할 수 있습니다.

자동 등록된 리소스에서 첫 메트릭 확인

새 데이터베이스로 Konduo를 처음 실행하면 다음 두 리소스가 자동으로 등록됩니다.

Konduo 자체 리소스
Konduo의 주 데이터베이스로 사용하는 PostgreSQL 리소스

따라서 이 실습에서는 두 리소스를 처음부터 만들 필요가 없습니다. Prometheus 메트릭 소스를 등록하고 연결하면 바로 직접 수집 흐름을 시험할 수 있습니다.

상단 메뉴에서 설정을 열고 메트릭 소스를 선택합니다.
Prometheus 메트릭 소스를 추가합니다.
이름은 알아보기 쉽게 Prometheus로 지정합니다.
URL에는 백엔드 컨테이너에서 접근할 주소인 http://prometheus:9090을 입력합니다. 브라우저에서 여는 http://localhost:9090과 구분해야 합니다.
연결 테스트를 실행한 뒤 저장합니다.
리소스 목록에서 자동 등록된 Konduo와 PostgreSQL을 확인합니다.
각 리소스의 메트릭 설정에서 방금 등록한 Prometheus를 연결하고 저장합니다.
수집 상태가 정상인지 확인한 뒤 리소스 대시보드에서 메트릭을 확인합니다.

여기서 Prometheus를 생략하는 것은 아닙니다. 생략되는 것은 Prometheus의 PostgreSQL·Konduo 수집 대상 설정입니다. Konduo가 두 시스템의 메트릭을 직접 수집해 Prometheus에 기록하고, 대시보드와 알림 규칙은 Prometheus에 저장된 시계열 데이터를 조회합니다.

다음 단계

첫 메트릭까지 확인했다면 이제 Konduo가 관찰하고 운영할 다른 대상을 연결할 수 있습니다.

필요하면 매뉴얼에서 설치/운영 절차 확인
Redis, Kafka, MySQL/MariaDB, etcd, Keycloak, Milvus, OpenSearch, Synology, Host 같은 리소스 추가
리소스가 직접 수집을 지원하면 Prometheus 메트릭 소스를 연결하고, 그렇지 않으면 필요한 exporter와 Prometheus 수집 대상 설정 추가
대시보드와 알림 규칙 확인
Email, Webhook, Telegram 알림 채널 연결
운영 검증용 이미지 태그나 digest 고정

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

정리 체크리스트

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

pletorco/konduo-backend, pletorco/konduo-frontend 이미지를 사용했는가?
매뉴얼을 포함했다면 pletorco/konduo-manual-ce 이미지를 사용했는가?
KONDUO_SECRET_KEY를 생성하고 안정적으로 보관했는가?
PostgreSQL 볼륨이 유지되는가?
Prometheus에 --web.enable-remote-write-receiver가 적용되어 있는가?
자동 등록된 Konduo와 PostgreSQL 리소스가 보이는가?
Prometheus 메트릭 소스를 두 리소스에 연결했는가?
두 리소스의 수집 상태와 대시보드 메트릭을 확인했는가?
매뉴얼을 포함했다면 http://localhost:5173/manual/에서 매뉴얼이 열리는가?
admin-bootstrap-status가 complete인지 확인했는가?
생성한 관리자 계정으로 로그인해 최초 비밀번호를 변경했는가?
외부 노출 전에 TLS, 방화벽, 백업, tag pinning을 검토했는가?

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

함께 읽기 좋은 글

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

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