Docker 모드 패치

변경 사항​

이번 패치의 주요 변경 사항을 요약하면 다음과 같습니다.

공통 사전 준비​

이후 모든 명령은 아래 한 줄부터 시작합니다. INSTALL_DIR 은 현재 설치된 exemONE 설치 폴더 경로입니다. (기존 EXEMONE_HOME 과 혼동을 피하기 위해 패치 작업 전용 변수로 분리합니다.)

# 실제 설치 경로로 수정해주세요.
export INSTALL_DIR=/home/exemone/exemone
cd $INSTALL_DIR

신규 패키지 파일 배치​

담당자에게 받은 신규 패키지 tar 파일을 /tmp 에 올려두세요.

ls -lh /tmp/exemone-pkg-*.tar.gz

신규 패키지 풀기 (도커 모드)​

도커 패키지는 2중 구조입니다. 바깥 tar 를 풀면 agent / docker / image / installer / install.sh 가 보이고, 실제 패치에 사용할 파일(onectl, scripts, docker-compose.yml 등) 은 installer/exemone.tar.gz 안에 있습니다.

# 1) 바깥 tar 풀기
mkdir -p /tmp/patch
tar -zxf /tmp/exemone-pkg-*.tar.gz -C /tmp/patch

# 바깥 구조 확인: agent, docker, image, installer, install.sh
ls /tmp/patch/exemone

# 2) 안쪽 installer tar 풀기 (그 자리에서)
tar -zxf /tmp/patch/exemone/installer/exemone.tar.gz \
    -C /tmp/patch/exemone/installer

export NEW_PKG=/tmp/patch/exemone/installer/exemone
ls $NEW_PKG    # onectl, scripts, docker-compose.yml 등이 보이면 OK입니다.

# 기존 exemone package 경로
export INSTALL_DIR=/home/exemone/exemone/installer/exemone

💡 참고: image/*.tar.gz 는 도커 이미지 파일입니다. 도커 모드 §2-2 (5) 단계에서 /tmp/patch/exemone/image/ 경로에서 docker load -i 로 적재합니다.

env 파일 교체 시 공통 원칙​

이번 버전에서 교체가 필요한 env 계열 파일(.env, kafka.env 등)은 고객사마다 커스텀 값이 들어가 있을 수 있습니다. 교체 전에 반드시 diff 로 차이를 확인하시고, 고객사 커스텀이 있으면 수동으로 병합하세요.

# 예시
diff $INSTALL_DIR/kafka.env $NEW_PKG/kafka.env

2. 도커(Docker) 모드​

2-1. 컨테이너 중지​

컨테이너를 모두 중지하고 상태를 확인합니다.

cd $INSTALL_DIR
./scripts/shutdown.sh
docker ps

모두 Exited 상태인지 확인해주세요.

2-2. ⭐ 이번 버전 고유 작업 (도커)​

⚠️ 주의: 본 단계를 진행하기 전에 $INSTALL_DIR, $NEW_PKG 환경변수가 반드시 지정되어 있어야 합니다.

(1) onectl 관련 작업 — 이번 버전부터 도커 모드에도 onectl 추가​

이전까지 도커 모드에는 onectl 이 없었지만, 이번 버전부터 바이너리/도커 공통 CLI로 onectl 바이너리가 추가됩니다. onectl이 사용하는 web/backend/data/history.db 신규 파일도 함께 배치합니다.

# 신규 onectl 배치
cp $NEW_PKG/onectl $INSTALL_DIR/onectl
chmod 755 $INSTALL_DIR/onectl

(2) scripts/ 폴더 교체​

아주 오래된 설치 환경에서는 현재 스크립트 일부가 누락되어 있을 수 있으므로, 기존 폴더를 백업하고 신규 폴더로 교체합니다.

# 기존 scripts 백업
mv $INSTALL_DIR/scripts $INSTALL_DIR/scripts.old

# 새 scripts 복사
cp -a $NEW_PKG/scripts $INSTALL_DIR/scripts

# 권한
chmod -R 755 $INSTALL_DIR/scripts

(3) kafka.env 업데이트 (고객사 커스텀 확인 후 교체)​

kafka.env 는 고객사마다 커스텀 값이 들어 있을 수 있으므로, 반드시 diff 로 차이를 확인한 뒤 교체합니다. 커스텀 값이 있으면 수동으로 병합하세요.

# 차이 확인
diff $INSTALL_DIR/kafka.env $NEW_PKG/kafka.env

# 기존 파일 백업
cp $INSTALL_DIR/kafka.env $INSTALL_DIR/kafka.env.old

# 커스텀이 없으면 바로 교체
cp $NEW_PKG/kafka.env $INSTALL_DIR/kafka.env

# 커스텀이 있으면: 위 cp 대신 vi 로 양쪽 값 병합 후 저장

(4) Nginx http.conf 업데이트 (고객사 커스텀 확인 후 교체)​

이번 버전에서 http.conf 에 gzip 압축 블록이 추가됐습니다. 다만 TLS 인증서 경로, proxy 헤더, 커스텀 location 블록 등 고객사마다 수정된 내용이 있을 수 있으므로 diff 로 반드시 확인 후 교체합니다.

# 차이 확인
diff $INSTALL_DIR/containers/exemone-https/conf.d/http.conf \
     $NEW_PKG/containers/exemone-https/conf.d/http.conf

# 기존 파일 백업
cp $INSTALL_DIR/containers/exemone-https/conf.d/http.conf \
   $INSTALL_DIR/containers/exemone-https/conf.d/http.conf.old

# 커스텀이 없으면 바로 교체
cp $NEW_PKG/containers/exemone-https/conf.d/http.conf \
   $INSTALL_DIR/containers/exemone-https/conf.d/http.conf

수동 병합 시 — gzip 블록 추가 위치와 내용​

커스텀 내용이 있어서 직접 병합해야 한다면, 기존 파일의 server { ... } 블록 안에서 ssl_* 지시어 바로 아래, # proxy 주석 위에 아래 블록을 추가하시면 됩니다.

server {
    listen 8443 ssl;
    ...
    ssl_session_cache shared:SSL:10m;
    ssl_session_timeout 10m;
    ssl_prefer_server_ciphers on;

    # ↓↓↓ 여기에 gzip 블록 추가 ↓↓↓
    # gzip 압축
    gzip on;
    gzip_comp_level 5;
    gzip_min_length 1024;
    gzip_vary on;
    gzip_proxied any;
    gzip_http_version 1.1;

    gzip_types
        text/plain
        text/css
        application/javascript
        application/json
        application/xml
        image/svg+xml;
    # ↑↑↑ 여기까지 ↑↑↑

    # proxy
    proxy_buffer_size 8k;
    proxy_buffers 16 8k;
    ...
}

(5) 신규 이미지 파일 적재​

신규 패키지의 image/ 폴더에 새 버전의 도커 이미지 tar 파일이 들어 있습니다. docker load -i 로 일괄 적재합니다.

# 일괄 로드 (한 줄)
ls /tmp/patch/exemone/image/*.tar.gz | xargs -L 1 docker load -i

# 로드된 이미지 확인
docker images | grep -E "v3.0.604|1.28"

(6) .env 업데이트 (수동 병합)​

.env 에는 초기 설치 시 채워진 사이트별 값이 들어 있어, 신규 파일로 통째로 덮어쓰면 안 됩니다. diff 로 차이를 확인한 뒤 vi 로 직접 편집해주세요.

보존해야 하는 키 (덮어쓰지 말 것):

신규 값으로 갱신해야 하는 라인:

# 차이 확인
diff $INSTALL_DIR/.env $NEW_PKG/.env

# 백업
cp $INSTALL_DIR/.env $INSTALL_DIR/.env.old

# 위 diff 결과를 보고 vi 로 수동 병합해주세요.
vi $INSTALL_DIR/.env

(7) 로그 로테이션 설정​

postgresql, redis, cache, front, https 의 로그 로테이션/리텐션은 호스트의 logrotation 툴을 통해 관리하므로 초기 설정을 진행합니다.

# log관리 프로세스 실행
$INSTALL_DIR/scripts/setup-logrotate.sh

(8) redis dockerfile 추가​

cp -R $NEW_PKG/dockerfile/redis $INSTALL_DIR/dockerfile

(9) exemone-redis containers 추가​

cp -R $NEW_PKG/containers/exemone-redis $INSTALL_DIR/containers

(10) docker-compose.yml 복사​

# 차이 확인
diff $INSTALL_DIR/docker-compose.yml $NEW_PKG/docker-compose.yml

# 백업
cp $INSTALL_DIR/docker-compose.yml $INSTALL_DIR/docker-compose.yml.old

# 위 diff 결과를 보고 vi 로 수동 병합해주세요.
vi $INSTALL_DIR/docker-compose.yml

2-3. 컨테이너 기동​

cd $INSTALL_DIR
./onectl restart all

# 검증
./onectl stat

# log관리 프로세스 실행
$INSTALL_DIR/scripts/setup-logrotate.sh

주의사항 및 참고​

• .env, kafka.env, http.conf, docker-compose.yml 등은 고객사 커스텀 값이 포함될 수 있으므로 반드시 diff 로 차이를 확인한 후 교체하거나 수동 병합하세요.
• 본 패치를 진행하기 전에 $INSTALL_DIR, $NEW_PKG 환경변수가 정확히 지정되어 있는지 확인해주세요. 도커 모드는 2중 tar 구조이므로 installer/exemone.tar.gz 까지 풀어야 한다는 점을 기억해주세요.
• 이번 버전부터 도커 모드에도 onectl 바이너리가 신규 도입됩니다. 기존 도커 모드 사용자도 onectl 사용에 익숙해질 필요가 있습니다.
• 신규 도커 이미지를 적재하지 않으면 컨테이너 기동 시 이미지 누락 오류가 발생할 수 있습니다. docker images | grep -E "v3.0.604|1.28" 명령으로 반드시 사전 확인해주세요.
• KAFKA_OPTS 의 MaxDirectMemorySize 가 3G → 6G로 상향됩니다. 호스트 메모리 자원이 충분한지 점검해주세요.
• 미들웨어 버전(REDIS_VERSION, POSTGRES_VERSION)에도 변경이 있으므로 .env 갱신 시 반드시 확인해주세요.
• setup-logrotate.sh 는 컨테이너 기동 후 한 번 더 실행하여 로그 로테이션이 정상 적용되었는지 확인할 수 있습니다.

※ Repository 내 테이블 변경사항 업데이트가 필요합니다.