Skip to content

refactor: 설치 문서 품질 개선 및 일관성 향상 #604

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Draft
jk-kim0 wants to merge 7 commits into
base: main
Choose a base branch
from
Draft

refactor: 설치 문서 품질 개선 및 일관성 향상 #604

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
7 commits
Select commit Hold shift + click to select a range
52bf807
refactor: 설치 문서 구조 개선 및 일관성 향상
jk-kim0 Feb 5, 2026
c92768d
refactor: 하위 문서 섹션 제목 일관성 개선
jk-kim0 Feb 5, 2026
c6e5e31
refactor: Community Edition 및 MCP 문서 섹션 수준 조정
jk-kim0 Feb 5, 2026
6c9b6f5
refactor: AWS EKS 설치 가이드 섹션 수준 조정
jk-kim0 Feb 5, 2026
3822d1f
refactor: 서버 구성 요구사항 요약표 섹션 수준 조정
jk-kim0 Feb 5, 2026
657ac3b
refactor: 서버 요구사항 문서에 요약 테이블 추가
jk-kim0 Feb 7, 2026
11f300a
fix: 환경변수 문서의 링크 개선
jk-kim0 Feb 7, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
48 changes: 40 additions & 8 deletions src/content/ko/installation.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4,18 +4,50 @@ title: '제품 설치'

# 제품 설치

QueryPie ACP 는 모든 버전에 대해 사전 빌드된 Docker 이미지를 제공하며, Public Cloud 의 Linux VM 또는 On-Premise 환경의 리눅스 서버 환경에서, 쉽고 빠르게 설치할 수 있습니다.
설치를 위한 인스턴스의 사양으로 4 vCPU, 16 GiB Memory, 100 GiB 이상의 Disk 공간을 권장합니다.
QueryPie ACP는 Docker 이미지로 제공되며, Public Cloud의 Linux VM 또는 On-Premise 환경에서 설치할 수 있습니다.

상세한 설치 안내는 다음의 문서를 참조하세요:
## 빠른 시작

* [설치 전 준비사항](installation/prerequisites)
* [설치하기](installation/installation)
처음 사용하시는 분은 Community Edition으로 시작하는 것을 권장합니다.

* [QueryPie ACP Community Edition](installation/querypie-acp-community-edition) - 5명 이하의 사용자를 위한 무료 버전
* [MCP 설정 가이드](installation/querypie-acp-community-edition/mcp-configuration-guide)

## 설치 가이드

설치 과정은 다음 순서로 진행합니다.

### 1. 설치 전 준비

* [설치 전 준비사항](installation/prerequisites) - 서버 환경, 컨테이너 엔진, 네트워크 요구사항
* [리눅스 배포본과 Docker, Podman 지원 현황](installation/prerequisites/linux-distribution-and-docker-podman-support-status)
* [Podman으로 Rootless Mode 구성하기](installation/prerequisites/configuring-rootless-mode-with-podman)

### 2. 설치하기

* [설치하기](installation/installation) - 설치 방법 개요
* [설치 가이드 - setup.v2.sh](installation/installation/installation-guide-setupv2sh) - 권장하는 자동화 설치 방법
* [설치 가이드 - 간단한 구성](installation/installation/installation-guide-simple-configuration) - 수동 설치 방법
* [setup.sh, setup.v2.sh 비교](installation/installation/comparison-of-setupsh-and-setupv2sh)
* [AWS EKS 환경에서 설치하기](installation/installation/installing-on-aws-eks) - Kubernetes 환경 설치

### 3. 설치 후 설정

* [라이선스 설치](installation/license-installation)
* [설치 후 초기 설정](installation/post-installation-setup) - Web Base URL, Proxy 주소 설정

## 참조 문서

설치 및 운영에 필요한 상세 정보입니다.

* [제품 버전](installation/product-versions) - 설치 가능한 버전 정보
* [시스템 아키텍처와 네트워크 접근제어](installation/system-architecture-and-network-access-control)
* [컨테이너 환경변수](installation/container-environment-variables)
* [라이선스 설치](installation/license-installation)
* [DB_MAX_CONNECTION_SIZE 최적화](installation/container-environment-variables/optimizing-dbmaxconnectionsize)
* [QUERYPIE_WEB_URL](installation/container-environment-variables/querypieweburl)
* [서버구성 요구사항](installation/server-configuration-requirements)
* [QueryPie ACP Community Edition](installation/querypie-acp-community-edition)
* [MCP 설정 가이드](installation/querypie-acp-community-edition/mcp-configuration-guide)
* [서버구성 요구사항 요약표](installation/server-configuration-requirements/server-configuration-requirements-summary)
* [Public Cloud 운영서버 요구사항](installation/server-configuration-requirements/public-cloud-production-server-requirements)
* [On-Premise VM 요구사항](installation/server-configuration-requirements/on-premise-vm-requirements)


19 changes: 11 additions & 8 deletions src/content/ko/installation/container-environment-variables.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -6,10 +6,13 @@ import { Callout } from 'nextra/components'

# 컨테이너 환경변수

QueryPie ACP 의 Server Container 를 실행하는데 필요한 환경변수에 대한 안내를 제공합니다.
이 문서는 QueryPie 10.3.0 또는 이후 버전에 적용됩니다.
QueryPie Server Container를 실행하는 데 필요한 환경변수를 안내합니다.

### 기본 환경변수
<Callout type="info">
이 문서는 QueryPie 10.3.0 이상 버전에 적용됩니다.
</Callout>

## 기본 환경변수

| **Environment Variable Name** | **Default Value** | **Description** |
| ------------------------------- | -------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
Expand All @@ -27,10 +30,10 @@ QueryPie ACP 의 Server Container 를 실행하는데 필요한 환경변수에
| DB_DRIVER_CLASS | `org.mariadb.jdbc.Driver` | Meta DB 가 AWS Aurora 인 경우, Aurora Instance 부분 장애시 Failover 를 지원합니다.AWS Aurora 를 적용하여 Failover 기능을 사용하려는 경우, AWS에서 제공하는 전용 드라이버 `software.amazon.jdbc.Driver` 를 지정합니다. |
| REDIS_NODES | | QueryPie Redis 에 연결하기 위한 Host, Port 정보를 입력합니다. 둘 이상의 Host, Port 정보를 입력하는 경우, `Host1:Port1,Host2:Port2` 와 같이, `,` 로 구분하여 입력할 수 있습니다.PoC 용도로 Single Machine 에 QueryPie Container, Redis Container 등을 모두 설치하는 경우, `host.docker.internal:6379` 을 입력하면 됩니다.Host 는 IP Address 형태를 입력하여도 되고, FQDN 을 입력하여도 됩니다. |
| REDIS_PASSWORD | | 권장하는 값: 16-char random string via `openssl rand -hex 8`Redis Password |
| DAC_SKIP_SQL_COMMAND_RULE_FILE | `skip_command_config.json` | 3rd Party Tool (DataGrip, DBeaver 등 워크벤치 툴) 에서 이용자가 입력하는 쿼리가 아닌, 툴이 자동으로 실행하는 SQL Query 를 Audit Log 에 남기지 않도록 설정합니다.툴이 자동으로 실행하는 SQL Query 는 구문의 패턴이 정해져 있다는 의미에서, 정형화된 Query 라고 부르기도 합니다.이러한 정형화된 Query 를 Audit Log 에 남기지 않도록 설정하면, 이용자가 체감하는 3rd Party Tool 의 응답속도가 빨라지게 됩니다. QueryPie Server 의 성능 부하를 감소시키는데, 도움이 됩니다.자세한 내용은 [Unknown Title#환경변수 추가.2](https://chequer.atlassian.net/wiki/spaces/QCP/pages/851346405/10.2.x#%ED%99%98%EA%B2%BD%EB%B3%80%EC%88%98-%EC%B6%94%EA%B0%80.2) 문서에서 확인할 수 있습니다. |
| DAC_SKIP_SQL_COMMAND_RULE_FILE | `skip_command_config.json` | 3rd Party Tool (DataGrip, DBeaver 등 워크벤치 툴) 에서 이용자가 입력하는 쿼리가 아닌, 툴이 자동으로 실행하는 SQL Query 를 Audit Log 에 남기지 않도록 설정합니다.툴이 자동으로 실행하는 SQL Query 는 구문의 패턴이 정해져 있다는 의미에서, 정형화된 Query 라고 부르기도 합니다.이러한 정형화된 Query 를 Audit Log 에 남기지 않도록 설정하면, 이용자가 체감하는 3rd Party Tool 의 응답속도가 빨라지게 됩니다. QueryPie Server 의 성능 부하를 감소시키는데, 도움이 됩니다.자세한 내용은 [릴리스 노트 10.2.x - 환경변수 추가](https://chequer.atlassian.net/wiki/spaces/QCP/pages/851346405/10.2.x#%ED%99%98%EA%B2%BD%EB%B3%80%EC%88%98-%EC%B6%94%EA%B0%80.2) 문서에서 확인할 수 있습니다. |


### 더이상 사용되지 않는 환경변수
## 더 이상 사용되지 않는 환경변수

<table>
<colgroup>
Expand Down Expand Up @@ -67,7 +70,7 @@ Web Console 에 접근하기 위한 QueryPie 의 URL 주소입니다. <br/>(예
이 URL 은 아래의 용도로 사용됩니다.
* SSO Integration 의 인증 과정에서, callback 주소로 사용됩니다.
* Web Console 에서 User Agent 를 내려받는 링크에 사용됩니다.
* 그 외 자세한 용도는, [https://chequer.atlassian.net/wiki/spaces/QCP/pages/876937310](https://chequer.atlassian.net/wiki/spaces/QCP/pages/876937310) 를 참조하시기 바랍니다.
* 그 외 자세한 용도는, [QUERYPIE_WEB_URL](container-environment-variables/querypieweburl) 문서를 참조하시기 바랍니다.
</td>
</tr>
<tr>
Expand Down Expand Up @@ -153,7 +156,7 @@ SAC &gt; RDP(WinSAC) 세션 레코딩에 사용하는 이미지를 EC2 인스턴
</table>


### FAQ
## FAQ

#### Q: DB_HOST, REDIS_HOST 에 127.0.0.1 이나 localhost 를 사용할 수 있나요?

Expand Down Expand Up @@ -234,7 +237,7 @@ Redis는 다음과 같은 목적으로 사용됩니다.
그 시점에 실행 중이던 특정 작업, 이용자 요청이 실패하게 됩니다.
Redis 와 QueryPie Container 를 재시작하게 되면, QueryPie Container 가 정상적으로 작동하게 됩니다.

### 고급기능을 위한 환경변수
## 고급 기능을 위한 환경변수

[Environment Variables for Advanced Setup - 10.3.x (KO)](https://querypie.atlassian.net/wiki/spaces/QCP/pages/954597480) 페이지를 참조하세요.

Expand Down
32 changes: 15 additions & 17 deletions ...installation/container-environment-variables/optimizing-dbmaxconnectionsize.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4,11 +4,9 @@ title: 'DB_MAX_CONNECTION_SIZE 최적화'

# DB_MAX_CONNECTION_SIZE 최적화

### Overview
QueryPie MySQL 연결 설정에 사용되는 Database Connection Pool Size를 최적화하는 방법을 안내합니다.

QueryPie MySQL 연결 설정에 사용되는 Database Connection Pool Size 를 최적화하는 방법을 안내합니다.

#### QueryPie MySQL 의 구성
## QueryPie MySQL의 구성

QueryPie Server 는 MySQL Database 에 Meta DB, Snapshot DB, Log DB 를 구성하여 작동합니다.

Expand All @@ -18,30 +16,30 @@ QueryPie Server 는 MySQL Database 에 Meta DB, Snapshot DB, Log DB 를 구성

QueryPie Server 는 Spring framework 를 사용하는 컴포넌트를 갖고 있으며, 이 컴포넌트에서는 Database Connection Pool 을 구성하여, QueryPie MySQL 에 데이터를 저장합니다.

### Database Connection Pool Size 설정하기
## Database Connection Pool Size 설정하기

QueryPie Server Container 를 실행할 때, 환경변수를 이용하여, Database Connection Pool Size 를 설정할 수 있습니다.

#### `DB_MAX_CONNECTION_SIZE`
### `DB_MAX_CONNECTION_SIZE`

Meta DB 를 위한 DB Connection Pool Size 를 지정합니다.
기본값은 20 입니다.

#### `LOG_DB_MAX_CONNECTION_SIZE`
### `LOG_DB_MAX_CONNECTION_SIZE`

Log DB 를 위한 DB Connection Pool Size 를 지정합니다.
기본값은 `DB_MAX_CONNECTION_SIZE` 에 설정된 값입니다.
별도로 `LOG_DB_MAX_CONNECTION_SIZE` 를 설정하지 않으면, `DB_MAX_CONNECTION_SIZE` 의 값과 동일한 값이 설정됩니다.

Snapshot DB 의 Connection Pool Size 는 이용자가 제어할 필요성이 낮아서, 이 값을 제어하기 위한 환경변수를 제공하지 않습니다.

### 일반적인 이용자 사용량, 부하 발생의 경우
## 일반적인 이용자 사용량, 부하 발생의 경우

`DB_MAX_CONNECTION_SIZE` 의 기본값 20 을 그대로 사용하는 것을 권장합니다.
일반적인 경우에 두루 사용할 수 있는 Connection Pool Size 의 크기입니다.
PoC 환경 뿐만 아니라, 일반적인 Production 환경에서 충분히 처리성능을 낼 수 있는 수치를 기본값으로 권장하고 있습니다.

### 많은 사용량, 높은 부하 발생의 경우
## 많은 사용량, 높은 부하 발생의 경우

`DB_MAX_CONNECTION_SIZE` 의 값을 20~40 사이의 값으로 설정하는 것을 권장합니다.
적정한 범위 내에서 `DB_MAX_CONNECTION_SIZE` 가 높아지면, QueryPie 가 동시에 처리 가능한 부하의 양이 늘어납니다.
Expand All @@ -50,7 +48,7 @@ DB 서버의 처리성능이 높고, CPU 수가 많은 경우, `DB_MAX_CONNECTIO
Server Container 가 작동하는 Linux VM 의 처리성능이 높고, CPU 수가 많은 경우, `DB_MAX_CONNECTION_SIZE` 를 높입니다.
Server Container 의 수가 늘어나면, `DB_MAX_CONNECTION_SIZE` 를 낮춥니다.

### `DB_MAX_CONNECTION_SIZE`설정값 요약표
## `DB_MAX_CONNECTION_SIZE` 설정값 요약표

| **DB_MAX_CONNECTION_SIZE** | **Description** |
| ---------------------------- | -------------------------------------------------------------------------------- |
Expand All @@ -60,12 +58,12 @@ Server Container 의 수가 늘어나면, `DB_MAX_CONNECTION_SIZE` 를 낮춥니
| 10 | 운영 환경에서, MySQL 연결수를 줄이고자 하는 경우에 적합합니다. |
| 5 | PoC 에서 기능 테스트를 수행하는 경우, 운영 환경에서 사용자 수가 적은 경우에 적합합니다. |

### `DB_MAX_CONNECTION_SIZE`와 하드웨어 용량의 관계식
## `DB_MAX_CONNECTION_SIZE`와 하드웨어 용량의 관계식

개발팀 내부의 성능 최적화 테스트를 통해, `DB_MAX_CONNECTION_SIZE` 과 QueryPie Server VM, DB 의 하드웨어 처리용량 사이에 다음의 관계식이 있다는 것을 도출하였습니다.
이 관계식을 참조하여, `DB_MAX_CONNECTION_SIZE` 값을 설정하면, 최적의 처리성능을 얻는 동시에, 가능한 작은 `DB_MAX_CONNECTION_SIZE` 값을 설정할 수 있습니다.

#### QueryPie MySQL 을 분리구성하는 경우
### QueryPie MySQL을 분리 구성하는 경우

하나의 Linux VM 내에 QueryPie Server Container 와 QueryPie MySQL 을 함께 실행하지 않고, 별도의 VM 또는 Cloud Service 를 이용해, 분리된 MySQL Instance 를 구성하는 경우입니다.
Production 환경에 적용하는 것을 권장합니다.
Expand Down Expand Up @@ -96,7 +94,7 @@ minimum ( Application_CPU_Count / Application_Node_Count, RDS_CPU_Count ) * 10
= 27
```

#### 단일 Linux VM 구성의 경우
### 단일 Linux VM 구성의 경우

하나의 Linux VM 에 QueryPie Server Container, QueryPie MySQL 을 함께 실행하는 경우입니다.
PoC 환경에 사용하는 것이 적합합니다.
Expand All @@ -114,13 +112,13 @@ Application_CPU_Count * 2.5
```


### QueryPie MySQL 설정에서 충분한 연결수를 허용하기
## QueryPie MySQL 설정에서 충분한 연결수 허용하기

QueryPie Server 는 Connection Pool 을 이용하여 QueryPie MySQL 에 연결을 맺습니다.
만일, MySQL Database Server 가 충분한 연결수를 허용하지 않는 경우, QueryPie Server 가 MySQL 에 연결을 생성하지 못하고, 오작동하는 현상이 발생하게 됩니다.
이 문제 현상은 QueryPie MySQL 가 허용하는 연결수보다, QueryPie Server 가 요구하는 DB 연결수가 더 큰 경우에 발생합니다.

#### DB 연결을 생성하지 못하는 현상
### DB 연결을 생성하지 못하는 현상

Web Console 에서, `[API] Could not open JPA EntityManager for transaction` 라는 에러 메시지를 만나게 됩니다.

Expand All @@ -132,7 +130,7 @@ Web Console 에서, `[API] Could not open JPA EntityManager for transaction` 라
</figure>


#### 문제해결방법 1) QueryPie MySQL 이 허용하는 연결수를 늘이기
### 해결방법 1: QueryPie MySQL이 허용하는 연결수 늘이기

두 가지 설정값을 500 이상으로 늘이는 설정을 적용할 수 있습니다.
이를 통해, QueryPie Server 가 요구하는 DB 연결수보다, QueryPie MySQL 가 허용하는 연결수를 더 크게 설정할 수 있습니다.
Expand All @@ -143,7 +141,7 @@ Web Console 에서, `[API] Could not open JPA EntityManager for transaction` 라
* max_connections
* [https://dev.mysql.com/doc/refman/8.0/en/server-system-variables.html#sysvar_max_connections](https://dev.mysql.com/doc/refman/8.0/en/server-system-variables.html#sysvar_max_connections)

#### 문제해결방법 2) DB_MAX_CONNECTION_SIZE 를 줄이기
### 해결방법 2: DB_MAX_CONNECTION_SIZE 줄이기

QueryPie 이용자 수가 적고, 이용량 부하가 낮은 경우, `DB_MAX_CONNECTION_SIZE` 설정값을 줄일 수 있습니다.
이를 통해, QueryPie MySQL 가 허용하는 연결수보다, QueryPie Server 가 요구하는 DB 연결수를 더 작게 설정할 수 있습니다.
Expand Down
2 changes: 2 additions & 0 deletions src/content/ko/installation/container-environment-variables/querypieweburl.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -6,6 +6,8 @@ import { Callout } from 'nextra/components'

# QUERYPIE_WEB_URL

QUERYPIE_WEB_URL 환경변수의 용도와 설정 방법을 안내합니다.

## 개요

QUERYPIE_WEB_URL은 서비스 접근, 인증 연동, 데이터 다운로드, 외부 연동 및 Proxy 설정 등 다양한 경로에서 사용되어 필수로 설정이 필요합니다.
Expand Down
Loading