# 설치 및 파라미터 설정 {% hint style="info" %} **참고** Podman-compose는 Docker-compose 스타일의 yml 파일을 지원하기 때문에 동일한 yml 파일로 docker / podman 환경에서 모두 구동할 수 있다. {% endhint %} ## 1. **Docker / Podman 이미지 로드** 설치 파일이 준비된 디렉터리에서 아래의 명령을 수행하여 Docker / Podman 이미지를 로드한다. * **Docker:** ``` docker load -i sysmaster-db-{version}.tar ``` * **Podman:** ``` podman load -i sysmaster-db-{version}.tar ``` 이때 로드된 컨테이너 이미지 목록은 아래와 같다. * sysmaster-db-client:{version} * sysmaster-db-client-postgres:{version} * sysmaster-db-sdm:{version} * sysmaster-db-dbmanager:{version} * sysmaster-db-collector:{version} * sysmaster-db-analyzer:{version} * sysmaster-db-tmaxopensql-postgres:{version} * sysmaster-db-kafka-loggable:{version} * sysmaster-db-zookeeper-loggable:{version} {% hint style="info" %} **참고** **`docker images | grep sysmaster`** 명령어를 통해 컨테이너 이미지 목록을 확인할 수 있다. {% endhint %} *** ## 2. **Docker / Podman 서비스 정의** 설치 디렉터리에서 **docker-compose.yml** 파일을 열어 Docker-compose / Podman-compose 환경에 생성하는 10개의 서비스들에 대해 정의한다. 각 서비스에 대한 설명은 다음과 같다. | 서비스 | 설명 | | --------------- | -------------------------------------- | | client-gateway | 사용자가 브라우저를 통해 접속하여 요청하는 웹 서버 | | client-postgres | postgres 웹 서버. gateway를 통해 사용자에게 전달 | | sdm | 수집 정보를 조회하고 클라이언트와 통신하는 API 서버 | | dbmanager | 관제 데이터베이스에 대한 상태 확인과 Admin 기능을 수행하는 서버 | | collector | 관제 데이터베이스로부터 데이터를 수집하는 서버 | | analyzer | 수집한 정보를 가공해 분석 및 저장하는 서버 | | metadb | UI 관련 설정 정보를 저장하는 DB 서버 | | repodb | 관제 데이터베이스 수집 데이터를 저장하는 DB 서버 | | zookeeper | Kafka Broker 서버의 상태 관리 | | broker | Kafka Broker 서버 | *** ## 3. **설치 파라미터 설정** 설치 디렉터리에서 **.env 파일**을 열어 SysMaster DB for PostgreSQL의 설치에 필요한 파라미터 값을 설정한다. {% hint style="info" %} **참고** .env 파일이 없다면 **`vim .env`** 명령어를 이용해 생성한다. {% endhint %} 이때 각 파라미터들은 개행으로 구분하며, 파라미터 이름과 값 사이에는 공백 없이 등호를 하나 입력한다. ```shell CLIENT_PORT=443 ADMIN_USERNAME=admin ADMIN_PASSWORD=admin COLLECTOR_PORT=8292 METADB_PORT=25432 METADB_USER=sysmaster METADB_PASSWORD=sysmaster METADB_PATH=./meta METADB_CONF_PATH=./meta.conf REPODB_PORT=15432 REPODB_USER=sysmaster REPODB_PASSWORD=sysmaster REPODB_PATH=./repo REPODB_CONF_PATH=./repo.conf RETENTION_DAY=7 LOG_PATH=./logs LOG_RETENTION_DAY=30 LOG_FILE_SIZE=20MB LOG_TOTAL_SIZE=1GB LOG_LEVEL=info KAFKA_MESSAGE_MAX_BYTES=20971520 CONTAINER_LOG_PATH=/sysmaster/logs TIME_ZONE=Asia/Seoul SDM_HEAP_SIZE_MAX= SDM_HEAP_SIZE_MIN= ANALYZER_HEAP_SIZE_MAX= ANALYZER_HEAP_SIZE_MIN= COLLECTOR_HEAP_SIZE_MAX= COLLECTOR_HEAP_SIZE_MIN= DBMANAGER_HEAP_SIZE_MAX= DBMANAGER_HEAP_SIZE_MIN= NGINX_RESOLVER=127.0.0.11 ``` 해당 과정에서 설정하는 파라미터에 대한 설명은 다음과 같다. | 파라미터 이름 | 설명 | 초기값 | | -------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------- | | CLIENT\_PORT | UI 접속 URL의 포트 번호 | 443 | | ADMIN\_USERNAME | Admin 계정의 사용자 이름 | admin | | ADMIN\_PASSWORD | Admin 계정의 암호 | admin | | COLLECTOR\_PORT |

수집 모듈(PG Agent)이 접속할 포트 번호

\[참고] 관제 DB에서 접속할 수 있도록 SysMaster 서버에서 열려 있어야 함

| 8292 | | METADB\_PORT | Meta DB의 접속 포트 번호 | 25432 | | METADB\_USER | Meta DB의 슈퍼 사용자 이름 | sysmaster | | METADB\_PASSWORD | Meta DB의 슈퍼 사용자 암호 | sysmaster | | METADB\_PATH | Meta DB의 데이터 파일 경로 | ./meta | | METADB\_CONF\_PATH | Meta DB의 설정 파일 경로 | ./meta.conf | | REPODB\_PORT | Repository DB의 접속 포트 번호 | 15432 | | REPODB\_USER | Repository DB의 슈퍼 사용자 이름 | sysmaster | | REPODB\_PASSWORD | Repository DB의 슈퍼 사용자 암호 | sysmaster | | REPODB\_CONF\_PATH | Repository DB의 설정 파일 경로 | ./repo.conf | | RETENTION\_DAY | 수집 정보의 보관 주기 | 7 | | LOG\_PATH | 로그 생성 위치 | ./logs | | LOG\_RETENTION\_DAY | 로그 파일 보관 주기 | 1 | | LOG\_FILE\_SIZE | 로그 파일 하나의 최대 크기 | 100MB | | LOG\_TOTAL\_SIZE | 모듈 별 최대 로그 저장 용량 | 1000MB | | LOG\_LEVEL | 모듈 별 로그 레벨 | info | | CONTAINER\_LOG\_PATH | 컨테이너 내부 로그 경로 설정 | /sysmaster/logs | | KAFKA\_MESSAGE\_MAX\_BYTES |

카프카 메시지 사이즈 설정,
1MB \~ 2GB 범위로 설정 가능

| 20971520 Byte | | TIME\_ZONE | SysMaster DB 서버 Time-Zone 설정 | Asia/Seoul | | SDM\_HEAP\_SIZE\_MAX | SDM의 최대 힙 크기 |

현재 컨테이너 전체 메모리(free 명령어의 total mem 참고)의 1/4 이다.

\[참고] 현재 docker 기본 이미지는 openjdk:17-alpine 이다.

| | SDM\_HEAP\_SIZE\_MIN | SDM의 최소 힙 크기 |

현재 컨테이너 전체 메모리(free 명령어의 total mem 참고)의 1/64 이다.

\[참고] 현재 docker 기본 이미지는 openjdk:17-alpine 이다.

| | ANALYZER\_HEAP\_SIZE\_MAX | Analyzer의 최대 힙 크기 |

현재 컨테이너 전체 메모리(free 명령어의 total mem 참고)의 1/4 이다.

\[참고] 현재 docker 기본 이미지는 openjdk:17-alpine 이다.

| | ANALYZER\_HEAP\_SIZE\_MIN | Analyzer의 최소 힙 크기 |

현재 컨테이너 전체 메모리(free 명령어의 total mem 참고)의 1/64 이다.

\[참고] 현재 docker 기본 이미지는 openjdk:17-alpine 이다.

| | COLLECTOR\_HEAP\_SIZE\_MAX | Collector의 최대 힙 크기 |

현재 컨테이너 전체 메모리(free 명령어의 total mem 참고)의 1/4 이다.

\[참고] 현재 docker 기본 이미지는 openjdk:17-alpine 이다.

| | COLLECTOR\_HEAP\_SIZE\_MIN | Collector의 최소 힙 크기 |

현재 컨테이너 전체 메모리(free 명령어의 total mem 참고)의 1/64 이다.

\[참고] 현재 docker 기본 이미지는 openjdk:17-alpine 이다.

| | DBMANAGER\_HEAP\_SIZE\_MAX | DBMANAGER의 최대 힙 크기 |

현재 컨테이너 전체 메모리(free 명령어의 total mem 참고)의 1/4 이다.

\[참고] 현재 docker 기본 이미지는 openjdk:17-alpine 이다.

| | DBMANAGER\_HEAP\_SIZE\_MIN | DBMANAGER의 최소 힙 크기 |

현재 컨테이너 전체 메모리(free 명령어의 total mem 참고)의 1/64 이다.

\[참고] 현재 docker 기본 이미지는 openjdk:17-alpine 이다.

| | NGINX\_RESOLVER |

Podman 환경 전용 설정
NGINX에서 DNS 이름을 해석하기 위해, Sysmaster 내부 DNS 네트워크의 게이트웨이 주소를 지정. 이설정은 Podman 환경에서만 필요하며, Docker 환경 등 다른 런타임에서는 별도의 설정이 요구되지 않습니다.

| podman network inspect script\_sysmaster 로 확인 가능. | ### 3.1 Podman 환경에서 DNS Resolver 설정 Rootless podman 환경에서는 NGINX\_RESOLVER 패러미터 설정이 별도로 필요하다. 이는 시스마스터 기동 후 개별 컨테이너가 재기동 되는 상황에서의 재연결을 위해 필요하며 sysmaster 네트워크의 gateway ip 주소를 사용한다. 해당 값은 환경 / podman 기동마다 달라질 수 있다. 아래 예시에서 NGINX\_RESOLVER=10.89.0.1로 설정 후 시스마스터를 부팅하는 과정을 보여준다. ``` [tibero@smdb-podman ~]$ podman compose up --no-start [tibero@smdb-podman ~]$ podman network inspect script_sysmaster [ { "name": "script_sysmaster", "id": "e014d8811e9b51f417d578358ab41e2624a465d9026c7916f9ba7e4ce382f699", "driver": "bridge", "network_interface": "cni-podman1", "created": "2025-08-04T22:55:11.345378476-04:00", "subnets": [ { "subnet": "10.89.0.0/24", "gateway": "10.89.0.1" /// -> 이 주소를 사용. } ], "ipv6_enabled": false, "internal": false, "dns_enabled": true, "labels": { "com.docker.compose.project": "script", "io.podman.compose.project": "script" }, "ipam_options": { "driver": "host-local" } } ] /// .env 파일에 패러미터 설정하기 [tibero@smdb-podman ~]$ podman compose up -d ``` ### 3.2 Podman 환경에서 SysMasterDB 서버와 동일 호스트에 설치된 관제 DB 등록 {% hint style="info" %} 컨테이너(SysMasterDB) → 컨테이너(관제DB) 통신이 아닌 컨테이너(SysMasterDB) → 호스트머신(관제DB) 통신에 대한 설정이다. {% endhint %} Podman bridge 네트워크 환경에서 SysmasterDB 컨테이너가 동일 호스트에 설치된 관제 DB에 호스트 IP(예: 192.168.141.12) 로 접속을 시도할 경우, 컨테이너 → 호스트 방향의 **Hairpin NAT(DNAT loopback)** 가 기본적으로 보장되지 않아 **Connection Refused**가 발생할 수 있다. 이는 동일 서버 내 구성이라도 컨테이너와 호스트가 서로 다른 네트워크 네임스페이스에 존재하기 때문에 발생하는 Podman bridge 구조적 제약이다. 예시로, 컨테이너에 접속하여 `telnet 192.168.141.12 40010`을 수행하면 `Connection refused`로 실패하고, Host Gateway 경로 적용 후 `telnet host.docker.internal 40010`은 정상 접속되는 것으로 확인할 수 있다. #### 설정 방법 (YML 예시 + 관제 DB 접속 주소 변경) 해결을 위해 `docker-compose.yml`에 **Host Gateway 매핑**을 추가하고, 관제 DB 접속 주소를 **호스트 IP → host.docker.internal** 로 변경한다. 아래 예시처럼 서비스에 `extra_hosts`를 추가한다. ```yaml dbmanager: image: sysmaster-db-dbmanager:POSTGRES-X.X.X container_name: dbmanager hostname: dbmanager ... volumes: - ${LOG_PATH}/dbmanager:${CONTAINER_LOG_PATH}:z networks: sysmaster: aliases: - dbmanager restart: always # 이 부분 추가 extra_hosts: - "host.docker.internal:host-gateway" ``` 아래와 같이 관제 DB IP를 **host.docker.internal** 로 설정하면 동일 호스트에 설치된 관제 DB를 등록 할 수 있다.
*** ## 4. **Meta DB 및 Repository DB 파라미터 설정** 설치 디렉터리에서 **meta.conf**, **repo.conf** 파일을 통해 Meta DB 및 Repository DB 파라미터 값을 확인할 수 있다. 해당 conf 파일은 기본적으로 제공되는 설정값을 사용하되, 다음에서 설명하는 파라미터는 필요 시 구동 환경에 맞게 사용자가 직접 설정해준다. | 파라미터 이름 | 설명 | | -------------------- | -------------------------------------------------------------------------------------------------------------------- | | pg\_max\_connections | Meta DB(또는 Repository DB)의 최대 커넥션 수 | | pg\_owner\_id | 해당 DB 데이터 디렉토리 접근 권한 설정을 위한 Host OS의 사용자 ID(uid). 호스트 머신의 특정 유저에서 컨테이너 DB 디렉토리로 직접 접근하고 싶을 경우 해당 유저의 사용자 ID로 설정한다. | | pg\_group\_id | 해당 DB 데이터 디렉토리 접근 권한 설정을 위한 Host OS의 사용자 그룹 ID(gid). 호스트 머신의 특정 유저에서 컨테이너 DB 디렉토리로 직접 접근하고 싶을 경우 해당 유저의 그룹 ID로 설정한다. | | log\_timezone | Meta DB(또는 Repository DB)의 로그 시간 Time-Zone | {% hint style="info" %} **참고** Meta DB 및 Repository DB 파라미터 변경이 필요한 경우, 관련 파라미터 설정은 TmaxOpenSQL 사용 가이드를 참조할 수 있다. 그러나 관련 파라미터 설정을 임의 수정하는 경우, SysMaster DB 서버의 정상 동작이 보장되지 않는다. 따라서 위 표에 명시된 파라미터 외 다른 파라미터는, 기본 제공 설정값을 그대로 사용하는 것을 권장한다. 특히 **Podman-compose 환경**에서의 설치 시, **pg\_owner\_id와 pg\_group\_id 값을 직접 설정(변경)하는 경우 정상 동작하지 않을 수 있다.** Podman의 컨테이너는 Rootless모드로 동작하고, 컨테이너 내부의 root (owner\_id = 0, group\_id = 0)가 호스트 머신의 유저에 대응된다. 하지만 OpenSQL이 root 권한 상태에서의 설치 및 기동을 허용하고 있지 않기 때문에 기본 설정값을 사용하는 것을 권장한다. 또한 **Podman-compose 환경에서는 Host OS에서 조회되는 meta, repo 디렉터리의 소유자가 pg\_owner\_id, pg\_group\_id에 설정한 UID/GID에 대응하는 사용자명으로 표시되지 않을 수 있다.** 이는 Podman rootless 환경의 user namespace 매핑 방식에 따른 정상 동작이다. Podman rootless 환경에서는 컨테이너 내부의 UID/GID가 Host OS의 UID/GID와 1:1로 동일한 사용자를 의미하지 않을 수 있다. 예를 들어 Host OS의 sysmaster 사용자가 uid=1008이고 pg\_owner\_id를 1008로 설정하더라도, 컨테이너 내부의 uid=1008은 Host OS에서 sysmaster가 아닌 subordinate UID로 매핑될 수 있다. 따라서 **Host OS에서 meta, repo 디렉터리를 `ls -al` 명령으로 조회할 경우 소유자가 sysmaster가 아닌 숫자 UID/GID로 표시될 수 있다.** 이는 권한 변경 실패나 제품 오류가 아니며, 컨테이너 내부에서는 매핑된 UID/GID 기준으로 정상 접근된다. Host OS에서 숫자 UID/GID로 표시되는 데이터 디렉터리를 `chown` 등으로 임의 변경하지 않는 것을 권장한다. 임의로 소유자를 변경할 경우, 컨테이너 내부의 UID/GID 매핑과 파일 권한이 불일치하여 Meta DB 또는 Repository DB가 정상 기동하지 않을 수 있다. {% endhint %} --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://docs.tibero.com/sysmasterdb-for-postgresql1.0/8.3_manual/installation-guide/installation/docker-compose-podman-compose-environment/installation-parameters.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.