[2편] QueryPie ACP 커뮤니티 버전 설치하기 — 도입 검토를 위한 첫 실습 환경 만들기

지난 글에서 던진 질문은 “공격자가 이미 내부에 들어왔다면, 어디까지 움직일 수 있을까?”였다. 그 질문에 답하려면 접근통제 제품의 기능 목록을 읽는 것에서 한 걸음 더 나아가야 한다. 실제 환경에 올려 보고, 계정과 권한을 설정하고, 허용한 작업과 차단한 작업이 어떻게 기록되는지 확인해야 한다.

이번에는 그 출발점으로 내 Mac에 QueryPie ACP 커뮤니티 버전의 실습 환경을 만들었다. 도입 담당자가 재현할 수 있도록 환경, 설치 순서, 부딪힌 문제와 확인한 범위를 함께 남긴다. 작업 기준일은 2026년 11월 7일, 설치한 ACP 버전은 11.6.7이다.

이 글을 따라 읽는 방법: 각 단계에 ‘참고 매뉴얼’과 해당 문서의 절 이름을 함께 적었다. 공식 절차를 확인한 뒤 이번 실습 화면과 비교하면 된다. 프로젝트 분리, 외부 포트 16444 사용, 자원 사용량과 소요 시간은 이번 Mac 환경의 설정·관찰 결과다. 문서는 이후 변경될 수 있으므로 다른 버전을 설치한다면 최신 안내와 함께 확인하자.

이번에 확인한 범위: 이미지 다운로드와 데이터베이스 초기화, 서버 준비 상태, 커뮤니티 라이선스 등록, 기본 관리자 비밀번호 변경, 변경한 비밀번호로 로그인과 대시보드 접속까지 완료했다. 관리 화면의 Web Base URL도 저장하고 다시 확인했다. 실제 DB·서버·Kubernetes 접근통제는 다음 실습에서 검증한다.

1. 도입 검토용 실습 환경의 목표부터 정했다

이번 환경의 목적은 앞으로 이어질 기능 검증을 위한 작은 실험실을 만드는 것이다. DB 하나와 테스트 계정을 연결해 “누가 접속할 수 있는가”, “어떤 작업을 할 수 있는가”, “무엇이 기록되는가”를 차례로 확인하려고 한다.

공식 커뮤니티 안내는 ARM64·macOS와 Docker 조합을 시험 사용 용도로 구분하고 있다. 시험 사용 권장값은 4 vCPU, 메모리 16GiB, 디스크 30GiB 이상이다. 다중 사용자 프로덕션 권장값은 AMD64, 8 vCPU, 메모리 32GiB, 디스크 100GiB 이상이며 OS는 Linux 기반이다. 이번에는 Apple Silicon과 Docker Desktop을 사용했다. 고가용성, 백업·복구, 인증 연동과 로그 보관 설계는 별도로 검토해야 한다.

2. 노트북 사양과 Docker에 할당된 자원은 다르다

참고 매뉴얼: QueryPie ACP Community Edition의 ‘권장 서버 사양’. 여기서 시험 사용과 프로덕션 권장 사양을 구분해 확인했다. 운영 OS를 고를 때는 리눅스 배포본과 Docker, Podman 지원 현황도 함께 참고할 수 있다. 아래 표는 매뉴얼의 권장값이 아니라 직접 점검한 내 Mac의 값이다.

도입 검토를 시작할 때는 “메모리 32GB짜리 노트북이 있다”에서 끝내지 말고 Docker가 실제 사용할 수 있는 메모리까지 확인하는 것이 좋다. 이미지와 데이터베이스, 로그가 쌓일 디스크 공간도 필요하다. 위 값은 이번에 사용한 환경의 기록이며 제품의 최소 사양을 뜻하지 않는다.

3. 기존 QueryPie 환경을 보존하고 별도 실습 공간을 만들었다

참고 매뉴얼: 설치 가이드 - setup.v2.sh와 내려받은 패키지의 querypie/11.6.7/README.ko.md 중 ‘QueryPie ACP 를 자동으로 설치하고 실행하기’, ‘Docker 로 QueryPie ACP 수작업 실행하기’. 패키지만 준비하는 옵션은 실제 다운로드한 setup.v2.sh에서 확인했다. 프로젝트·네트워크·데이터 경로 분리는 기존 환경을 보존하려고 이번에 추가한 구성이다.

내 Mac에는 이미 다른 QueryPie 환경이 있었다. 기존 컨테이너를 종료한 뒤 새 Compose 프로젝트 이름을 acp-ce-lab로 정하고 네트워크와 데이터 경로를 분리했다. 기존 데이터를 새 실습 환경에 재사용하지 않았다.

공식 설치 스크립트는 자동 설치도 지원한다. 이번에는 기존 환경과 로그를 보존하기 위해 공식 Compose 패키지를 먼저 내려받고, 패키지에 포함된 README의 수동 실행 절차를 따랐다. 따라서 아래는 이번 환경에서 실제로 선택한 경로다.

curl -fsSL https://dl.querypie.com/setup.v2.sh -o setup.v2.shbash setup.v2.sh --install-compose-package 11.6.7bash setup.v2.sh --populate-env querypie/11.6.7/.envchmod 600 querypie/11.6.7/.env

실행 전 스크립트를 확인했고, 이때 스크립트 버전은 26.10.1이었다. 이후 명령은 생성된 querypie/11.6.7 디렉터리에서 실행했다. 환경 파일에는 인증 정보가 들어갈 수 있으므로 원문을 블로그나 저장소에 올리지 않는다.

4. 이미지를 받고 데이터베이스를 초기화했다

참고 매뉴얼: 패키지의 README.ko.md → Docker 로 QueryPie ACP 수작업 실행하기 → MySQL 및 Redis 실행하기 / QueryPie ACP Tools 실행하기. 아래 명령의 데이터베이스 기동과 migration 순서를 이 절에서 확인했다. 이미지 다운로드 진행 화면, health 응답과 소요 시간은 실제 실행하면서 기록했다. README는 Compose 패키지를 받은 뒤 설치 디렉터리에서 열어 볼 수 있다.

이번 구성은 ACP 애플리케이션, MySQL, Redis, 초기화에 쓰는 Tools 이미지로 이루어진다. MySQL은 제품 설정과 이력 등을 저장하는 기반이므로, 향후 연결할 업무용 DB와 구분해서 이해해야 한다. 컨테이너를 실행하는 것만큼 데이터가 어디에 남는지 확인하는 일도 중요하다.

docker compose --profile database --profile app --profile tools pulldocker compose --profile database up -ddocker compose --profile tools up -dcurl http://localhost:8050/healthdocker compose --profile tools exec -T tools /app/script/migrate.sh runalldocker compose stop tools

Tools의 health 응답이 200인 것을 확인한 후 migration을 실행했다. 이번에 받은 네 이미지의 아키텍처는 모두 arm64였다. 이미지 메타데이터의 크기 합계는 약 5.33GB였으며, 이 수치는 다운로드 전송량이나 실제 추가 디스크 사용량을 측정한 값은 아니다.

기록상 이미지 다운로드는 11시 53분 40초에 시작해 11시 56분 15초 전에 끝났다. 첫 migration은 11시 57분 52초부터 58초까지 진행됐다. 네트워크와 장비, 이미지 캐시 유무에 따라 달라질 수 있는 한 번의 실측이다. 사전 조사와 화면 촬영에 걸린 시간을 합쳐 제품의 설치 시간이라고 표현하지는 않겠다.

5. 실제로 만난 문제: 6443 포트 충돌

이번 환경에서 추가한 조치: 외부 포트를 16444로 바꾸는 것은 내 Mac의 충돌을 해결하기 위한 설정이며, 모든 설치에 필요한 공식 기본 절차는 아니다. 후속 Proxy 설정은 설치 후 초기 설정의 ‘KAC: Proxy 접속 주소 설정’을 참고한다. Docker의 포트 매핑 변경과 제품 안의 Proxy 주소 설정은 각각 확인해야 한다.

애플리케이션을 처음 올릴 때 6443 포트를 이미 사용 중이라는 오류가 발생했다. 확인해 보니 Docker Desktop이 로컬의 127.0.0.1:6443을 사용하고 있었다.

재시도에서는 기동됐지만, 기존 서비스와 명확히 분리하기 위해 실습 환경의 KAC 외부 포트를 16444로 바꿨다. 컨테이너 내부의 6443은 그대로 두고 호스트 포트만 변경했다. 최종 Compose 포트 목록에는 16444:6443이 들어간다.

lsof -nP -iTCP:6443 -sTCP:LISTENdocker compose port app 6443# 이번 환경의 결과: 0.0.0.0:16444

Compose override에서 포트 목록을 바꿀 때는 기존 목록에 의도치 않게 추가되는 일이 없도록 최종 설정을 확인해야 한다. 이번에는 Compose v5.6.1에서 ports: !override를 사용해 전체 포트 목록을 명시했다. 아래 캡처는 최초 오류 화면이 아니라, 점유 중인 포트와 변경 후 매핑을 확인한 화면이다.

이 변경만으로 Kubernetes 접근통제가 검증된 것은 아니다. 나중에 KAC 실습을 할 때는 사용자가 접속할 Proxy 주소와 포트에도 이 값을 반영해야 한다. 도입 담당자에게 중요한 점은 웹 관리 화면의 포트만 확인하면 끝나는 제품이 아니라는 것이다. 실제 자원 접근에 쓰는 경로와 방화벽 규칙을 함께 정리해야 한다.

6. 컨테이너가 떠 있는 것과 서비스 준비 완료를 구분했다

참고 매뉴얼: 패키지 README.ko.md의 ‘QueryPie ACP Application 실행하기’ 및 커뮤니티 에디션 안내의 ‘QueryPie ACP Community Edition의 수동 시작’, ‘설치 방법 → 3. 설치 후 접속’. readyz 확인 방법과 웹 접속 포트를 이 부분에서 확인했다.

docker compose --profile app up -ddocker compose exec -T app readyzdocker compose ps

컨테이너의 running 상태만 보지 않고 ACP의 readyz 명령으로 준비 완료를 확인했다. 포트 변경 후 첫 성공 기록은 12시 2분 11초였고, 화면을 남기면서 다시 확인했을 때도 성공했다.

웹 브라우저에서 http://localhost:8000/으로 접속하니 라이선스 등록 화면이 열렸다. 실행 직후 한 번 측정한 컨테이너 메모리는 app 약 3.99GiB, MySQL 약 550.8MiB, Redis 약 10.06MiB였다. 아직 사용자 작업을 수행하지 않은 상태의 순간 측정이므로 운영 용량 산정의 근거로 쓰기에는 부족하다.

7. 커뮤니티 라이선스 신청은 별도 단계였다

참고 매뉴얼: 커뮤니티 에디션 안내의 ‘설치 방법 → 2. 설치 중 라이선스 발급 받기 / 4. 라이선스 등록’. 신청은 공식 커뮤니티 라이선스 신청 페이지에서 진행했다. 매뉴얼의 파일 확장자 설명과 이번에 실제 받은 파일 형식의 차이는 아래에 따로 기록했다.

화면에는 최대 5명이 1년 동안 무료로 체험할 수 있다는 안내가 있었다. 공식 커뮤니티 신청 페이지에서 수신 가능한 업무 이메일과 테스트용 조직 정보를 입력했다. 신청 후 성공 메시지를 확인했고, 인증서가 첨부된 발급 메일도 도착했다.

수신한 발급 안내에는 COMMUNITY 유형과 활성 사용자 5명, DAC·KAC·SAC·WAC 제품 범위가 표시돼 있었다. 향후 독자가 신청할 때는 당시 제공 조건과 실제 발급된 라이선스를 다시 확인하는 것이 좋다. 기능 이름이 라이선스에 있다는 사실만으로 해당 기능의 사용성이나 우리 환경과의 호환성이 검증된 것은 아니다.

실제로 받은 파일은 ZIP 안의 .pem 인증서였다. 공식 안내에는 .crt로 설명된 부분도 있지만, 이번에는 ZIP을 풀어 나온 PEM 파일을 Upload License → Continue로 읽어 들였다. 조직명, Community 유형, 제품 범위와 사용자 제한을 확인한 후 Apply를 눌렀고 로그인 화면으로 넘어갔다.

8. 첫 로그인에서 비밀번호 변경을 마치고 대시보드에 들어갔다

참고 매뉴얼: 커뮤니티 에디션 안내의 ‘설치 방법 → 5. 로그인 / 6. 설치 완료’. 기본 계정과 비밀번호 변경 절차를 확인했다. 변경 강제화의 동작과 계정 관리 조건은 qp-admin 기본 계정에 대한 패스워드 변경 강제화 및 계정 삭제 기능의 ‘qp-admin 계정 패스워드 변경 강제화 조건 / 패스워드 변경 방법’을 참고했다. 이번 실습에서는 계정을 삭제하지 않았다.

공식 가이드의 기본 관리자 계정 qp-admin으로 로그인하자 비밀번호 만료 안내와 변경 화면이 나왔다. 새로운 비밀번호를 설정한 뒤 성공 메시지를 확인했고, 변경한 비밀번호로 다시 로그인해 사용자 대시보드에 들어갔다. 실습용 관리자 비밀번호는 별도로 안전하게 보관했다.

Go to Admin Page → General → Company Management → General로 이동해 Web Base URL을 http://localhost:8000으로 설정했다. 끝에 슬래시를 붙이지 않고 저장한 뒤, 페이지를 새로 불러와 값이 남아 있는 것도 확인했다. 이 주소는 이번 Mac 한 대에서 사용하는 실습 기준이다. 다른 PC나 외부 인증 시스템과 연동할 때는 그쪽에서도 접근 가능한 주소와 TLS 구성이 필요하다.

참고 매뉴얼: 설치 후 초기 설정의 ‘공통 설정 → QueryPie Web Base URL 설정’과 QueryPie ACP Community Edition 초기 구성 가이드의 ‘Web Base URL 설정’. 주소 끝의 슬래시를 제외하고 포트를 포함하는 방법을 확인했다. 같은 초기 구성 가이드의 ‘서비스 별 Proxy 설정’은 이후 외부 클라이언트 접속 실습을 따라갈 때 참고할 부분이며, 이번 글에서는 해당 설정을 완료하지 않았다.

관리자 화면 상단에는 WAC 인증서 갱신에 따른 WAC Proxy 재시작 안내가 표시됐다. 이번에 WAC 접속을 검증한 것은 아니며, 해당 구성 요소 적용 확인과 서비스별 Proxy 설정은 각 기능 실습에서 이어갈 항목으로 남겼다. 로그인 성공을 모든 접근 경로의 준비 완료로 간주하지 않는 것이 중요하다.

9. 도입 담당자가 이번 설치에서 가져갈 질문

첫 설치를 해보니, 도입 검토의 출발점은 제품 화면을 띄우는 것과 동시에 우리 환경의 제약을 드러내는 과정이었다. 이번에는 기존 데이터와 포트가 그 제약이었다. 운영으로 확대한다면 인증서, 계정 연동, 네트워크 경로, 장애 대응과 로그 보관이 같은 방식으로 검토 대상에 들어올 것이다.

다음 실습에서는 이 환경에 테스트 DB 하나를 연결할 예정이다. 그때부터는 “접속됐다”를 넘어, 권한이 없는 사용자의 접근이 거절되는지, 허용된 작업과 차단된 시도가 어떤 증거로 남는지를 확인해 보려 한다. 첫 글에서 제기한 ‘침투 이후 통제’라는 주장을 실제 동작으로 점검하는 출발점이다.

참고한 공식 자료

아래 목록은 본문에서 연결한 문서를 한곳에 모은 것이다. 설치·실습 및 문서 확인 기준일은 2026년 11월 7일이다. 스크린샷은 매뉴얼 이미지를 옮긴 것이 아니라 이번 실습에서 직접 촬영한 화면이다.

• QueryPie ACP Community Edition — 권장 서버 사양, 라이선스 신청·등록, 첫 로그인, 수동 시작과 준비 상태 확인.

• 설치 가이드 - setup.v2.sh — 공식 설치 스크립트의 설치 흐름.

• querypie/11.6.7/README.ko.md — 공식 Compose 패키지에 포함된 파일. ‘Docker 로 QueryPie ACP 수작업 실행하기’ 아래의 MySQL·Redis, Tools, Application 실행 절차.

• 리눅스 배포본과 Docker, Podman 지원 현황 — 운영 환경의 배포판과 컨테이너 엔진 선택 참고.

• 커뮤니티 라이선스 신청 페이지 — 실제 라이선스 발급 신청.

• qp-admin 기본 계정의 패스워드 변경 강제화 및 계정 삭제 기능 — 초기 비밀번호 변경 동작과 계정 관리 조건.

• 설치 후 초기 설정 — Web Base URL 설정 및 서비스별 Proxy 설정 참고.

• 커뮤니티 에디션 초기 구성 가이드 — Web Base URL의 입력 형식, 후속 실습에서 진행할 서비스별 Proxy 설정.

본문의 화면은 이번 실습 중 직접 촬영했다. 설치 성공, 라이선스 활성화, 기능 검증과 운영 적합성은 각각 확인할 항목으로 구분해 기록한다.