dockerinstaller를활용한_설치

v3.0.23.4 버전부터 docker installer를 통한 설치 방법을 지원합니다.

1. 개요​

• exem-kafka-agent_docker.bin은 exemOne Kafka Agent의 Docker 컨테이너 설치 및 업데이트를 수행하는 셀프 익스트랙팅 설치 파일입니다.
• 내부에 Docker 이미지(tar.gz), 설정 템플릿, start/stop 스크립트가 포함되어 있습니다.
• 별도의 Java 설치 없이 Docker만 설치되어 있으면 동작합니다.
• 컨테이너명: exemone-kafka-agent / 이미지: maxgauge/exemone-kafka-agent

2. 작업 유형​

2.1. 대화형 모드 메뉴​

2.2. 설정 파일 모드 (Silent mode)​

• 설정 파일을 인수로 전달하여 사용자 입력 없이 자동 설치/패치를 수행합니다.
• 설정 파일 모드에서는 항상 install(patch) 모드로 수행됩니다.
• 자세한 내용은 3.2. 설정 파일 모드 참고

2.3. Legacy 환경 감지​

• $EXEMONE_HOME 환경변수가 설정되어 있고 $EXEMONE_HOME/containers/exemone-kafka-agent 디렉토리가 존재하면 Legacy(exemone-package) 환경으로 감지합니다.
• Legacy 환경에서는 KAFKA_HOME이 $EXEMONE_HOME/containers/exemone-kafka-agent로 자동 설정됩니다.
• 대화형 모드에서는 Legacy 환경 감지 시 확인 프롬프트가 표시되며, n 입력 시 standalone 모드로 전환됩니다.

3. 실행 방법​

3.1. 대화형 모드 (Interactive)​

./exem-kafka-agent_docker.bin

• bin 파일을 실행하면 메뉴가 표시되고 각 항목을 입력합니다.

3.1.1. install(patch) 설치 과정​

1. bin 파일 실행
2. 모드 선택 - install(patch)
3. (Legacy 환경 감지 시) Legacy 설치 여부 확인
4. 설치 디렉토리 지정 (EXEM_HOME) — Legacy 환경은 자동 설정, 생략
5. 에이전트 필수 입력값 지정 (RECEIVER_IP, RECEIVER_PORT, EXEM_AGENT_NAME)
6. 입력 데이터 확인 → Y 입력 시 설치 진행, n 입력 시 재입력
7. Docker 이미지 로드
8. 설치 완료

3.1.2. unpack 설치 과정​

1. bin 파일 실행
2. 모드 선택 - unpack
3. 압축 해제 완료 — 현재 경로(bin 실행 위치)에 패키지 압축 해제 후 종료

3.2. 설정 파일 모드 (Silent mode)​

• 설정 파일을 인수로 전달하면 사용자 입력 없이 자동으로 설치/패치가 수행됩니다.
• 설정파일의 파일명은 자유이며, 절대경로/상대경로 모두 사용 가능합니다.
• KEY=VALUE 형식으로 한 줄에 하나씩 작성합니다.
• #으로 시작하는 줄은 주석으로 무시됩니다.

vi kafka-docker-install-file

INSTALL_DIR=/home/exem
RECEIVER_IP=10.20.30.40
RECEIVER_PORT=9009
EXEM_AGENT_NAME=kafka-agent

:wq!

• 설정파일 키

• 실행

./exem-kafka-agent_docker.bin kafka-docker-install-file

4. install 동작 상세​

4.1. 설치 디렉토리 설정​

• 기본값: 실행 위치 하위의 exem/ 디렉토리
• 입력 경로가 /exem으로 끝나지 않으면 자동으로 /exem이 추가됩니다.
• Kafka Agent는 {INSTALL_DIR}/kafka/에 설치됩니다.

예시) INSTALL_DIR = /home/exem  →  KAFKA_HOME = /home/exem/kafka

• Legacy 환경: KAFKA_HOME = $EXEMONE_HOME/containers/exemone-kafka-agent (자동 설정)

4.2. 신규 설치 vs 패치 자동 판별​

• {KAFKA_HOME} 디렉토리 존재 여부로 판별합니다.

4.3. 버전 표기 형식​

• 패키지 버전은 {바이너리 버전}-{패키지 인덱스} 형식으로 표기됩니다.
• 바이너리(에이전트 jar)가 동일하더라도 installer, 설정 파일 등 패키지 구성이 변경되면 인덱스만 증가합니다.

예시) 3.0.23.3-4
  agent   : 3.0.23.3  (바이너리 버전)
  package : 3.0.23.3-4  (패키지 버전)

5. 신규 설치​

5.1. 설치 완료 후 파일 구조​

exem/
└── kafka/
    ├── lib/
    │   └── exemone-kafka-agent-v{PKG_VERSION}.tar.gz   ← Docker 이미지 파일
    ├── cfg/
    │   ├── .env              ← 에이전트 설정 (버전, 수신기 주소 등)
    │   ├── kafka.conf        ← 에이전트 동작 설정
    │   └── cfg.reload        ← 설정 리로드 파일
    ├── log/
    ├── pkg_version.sh
    ├── start.sh
    └── stop.sh

5.2. cfg/.env 구성​

KAFKA_AGENT_VERSION=3.0.23.3-4
KAFKA_AGENT_NAME="kafka-agent"
KAFKA_AGENT_RECEIVER_ADDR="10.20.30.40:9009"
KAFKA_AGENT_RUN_PATH="/home/exem/kafka"
EXEM_RUN_ON_CONTAINER=true

5.3. 설치 완료 출력​

AGENT_VERSION=3.0.23.3
PKG_VERSION=3.0.23.3-4
INSTALL_DIR=/home/exem/kafka
RECEIVER_ADDR=10.20.30.40:9009
IMAGE=maxgauge/exemone-kafka-agent:v3.0.23.3-4
To start: /home/exem/kafka/start.sh
xmSuccess(0): installation completed

6. 패치​

• 기존 설치가 감지되면 자동으로 패치 모드로 진입합니다.
• 패치 시 실행 중인 컨테이너를 자동으로 중지하지 않습니다. 패치 완료 후 안내에 따라 수동으로 재시작해야 합니다.

6.1. 패치 동작​

1. 기존 cfg/.env 로드하여 기존 설정값을 기본값으로 표시
2. 변경할 설정값 입력 (RECEIVER_IP, RECEIVER_PORT, EXEM_AGENT_NAME)
3. Docker 이미지 로드 (신규 이미지 → 기존 이미지 삭제)
4. cfg/.env 업데이트
5. cfg/cfg.reload 업데이트
   • cfg/kafka.conf는 사용자 설정 보존을 위해 덮어쓰지 않음 (Legacy 환경)
   • standalone 환경: cfg/kafka.conf도 업데이트
6. start.sh, stop.sh, lib/, pkg_version.sh 업데이트
7. Legacy 환경 추가 동작: 이미지를 v prefix 없는 태그로 re-tagging, $EXEMONE_HOME/.env 업데이트

참고
패치 완료 후 에이전트는 자동으로 재시작되지 않습니다.
Legacy 환경: cd $EXEMONE_HOME && ./scripts/restart.sh kafka-agent
standalone 환경: stop.sh && start.sh

6.2. 패치 버전 출력​

Existing installation found. Running patch...
Existing version:
  agent   : 3.0.23.0
  package : 3.0.23.0-1
New version:
  agent   : 3.0.23.3
  package : 3.0.23.3-4

6.3. 패치 완료 출력​

KAFKA_HOME=/home/exem/kafka
OLD_AGENT_VERSION=3.0.23.0
OLD_PKG_VERSION=3.0.23.0-1
NEW_AGENT_VERSION=3.0.23.3
NEW_PKG_VERSION=3.0.23.3-4
IMAGE=maxgauge/exemone-kafka-agent:v3.0.23.3-4
To start: /home/exem/kafka/start.sh
xmSuccess(0): patch completed

7. unpack​

• 패키지 내용물을 현재 디렉토리에 압축 해제만 하고 종료합니다.

실행 위치/
└── exem/
    └── kafka/
        ├── lib/
        ├── cfg/
        ├── start.sh
        ├── stop.sh
        └── ...

• 완료 시 출력:

UNPACK_DIR={실행경로}/exem/kafka
xmSuccess(0): unpack completed

8. cfg/.env 파일​

• install 모드로 설치 시 {KAFKA_HOME}/cfg/.env에 저장되며, 이후 패치 시 기존 설정을 불러오는 데 사용됩니다.
• 컨테이너가 기동될 때 이 파일을 마운트하여 설정을 읽는다.

KAFKA_AGENT_VERSION=3.0.23.3-4
KAFKA_AGENT_NAME="kafka-agent"
KAFKA_AGENT_RECEIVER_ADDR="10.20.30.40:9009"
KAFKA_AGENT_RUN_PATH="/home/exem/kafka"
EXEM_RUN_ON_CONTAINER=true

• 값 변경이 필요할 경우 cfg/.env를 직접 수정한 후 stop.sh && start.sh로 재기동하면 됩니다.

9. 에이전트 시작/중지​

• 시작

sh {KAFKA_HOME}/start.sh

• start.sh 동작:

  • 컨테이너가 실행 중이면 → "already running" 출력 후 종료
  • 컨테이너가 중지 상태이면 → 기존 컨테이너 제거 후 새 이미지로 재생성 (패치 후에도 새 버전으로 기동됨)
  • 컨테이너가 없으면 → 신규 생성 후 기동

• 중지

sh {KAFKA_HOME}/stop.sh

• stop.sh 동작:
  • 컨테이너가 실행 중이면 → 중지
  • 컨테이너가 없거나 이미 중지 상태이면 → "not running" 출력 후 정상 종료

10. 에러 코드​