준비 사항
- x86_64/amd64 Linux 호스트와 Docker Engine(Compose 사용 시 Docker Compose v2)
- 호스트에서 접근 가능한 PostgreSQL 14 이상과 전용 DB·사용자
- 사용자 브라우저에서 접근할 내부 FQDN과 TLS 인증서/Reverse Proxy
- 애플리케이션 최소 12자, 운영 권장 20자 이상의 고유한 Bootstrap 관리자 비밀번호
- AES-256용 정확히 32바이트의 암호화 키
GitHub Release에는 jupiq 서비스 이미지 tar.gz만 첨부합니다. PostgreSQL 이미지는 포함하지 않으므로 기존 내부 PostgreSQL을 사용하거나 조직의 별도 반입 절차로 준비하세요.
1. 연결망에서 내려받고 오프라인망에 반입
- 릴리스 선택
GitHub Releases에서 승인된 버전의jupiq-v버전.tar.gz하나를 받습니다. - SHA-256 대조
Release 본문에 게시된 64자리 SHA-256을 별도 승인 기록에 남기고 내려받은 파일과 비교합니다.JUPIQ_ARCHIVE_SHA256='릴리스-본문의-SHA256' printf '%s %s\n' "${JUPIQ_ARCHIVE_SHA256}" jupiq-v1.8.7.tar.gz | sha256sum -c - - 반입 검사
조직의 악성코드·취약점·매체 반입 절차를 완료하고 파일명·버전·SHA-256을 함께 기록합니다. - gzip 무결성 확인
gzip -t jupiq-v1.8.7.tar.gz - Docker 이미지 로드
gzip -dc jupiq-v1.8.7.tar.gz | docker load docker image inspect jupiq:v1.8.7
2. 런타임 환경변수 네 개 설정
아래 내용으로 권한이 제한된 .env 파일을 직접 만듭니다. 애플리케이션은 다른 런타임 환경변수를 설정값으로 읽지 않습니다.
POSTGRES_DSN=postgres://jupiq:비밀번호@db.internal:5432/jupiq?sslmode=verify-full
BOOTSTRAP_ADMIN=admin
BOOTSTRAP_ADMIN_PASSWORD=충분히-긴-임시-관리자-비밀번호
ENCRYPTION_KEY=32바이트-AES-키| 변수 | 용도 | 운영 주의 |
|---|---|---|
POSTGRES_DSN | 상태·설정·감사 DB | 운영은 sslmode=verify-full 권장 |
BOOTSTRAP_ADMIN | 최초/긴급 로컬 관리자 ID | 개인 식별 가능한 전용 ID |
BOOTSTRAP_ADMIN_PASSWORD | 최초 로그인 비밀번호 | 배포 직후 변경 |
ENCRYPTION_KEY | DB 비밀값 AES-256 암호화 | 백업과 분리 보관, 유실 시 복구 불가 |
키 생성 예시:
openssl rand -base64 32raw 32문자, 표준/Raw base64로 인코딩된 32바이트, 64자 hex를 허용합니다. `.env`는 Git에 커밋하지 말고 권한을 제한하세요.
3. 서비스 기동
이미지 tar.gz만 반입한 경우 다음처럼 바로 실행할 수 있습니다.
docker run -d --name jupiq --restart unless-stopped --init \
--env-file .env -p 127.0.0.1:8080:8080 \
--read-only --tmpfs /tmp:size=64m,mode=1777 \
--cap-drop ALL --security-opt no-new-privileges:true \
jupiq:v1.8.7
curl --fail http://127.0.0.1:8080/healthz
curl --fail http://127.0.0.1:8080/readyzCompose를 사용하려면 같은 버전 소스의 .env.example과 compose.example.yaml을 별도로 반입해 docker compose --env-file .env -f compose.example.yaml up -d를 실행합니다. 두 텍스트 파일은 서비스 이미지 릴리스 자산에 포함되지 않습니다.
예제는 보안을 위해 호스트의 127.0.0.1:8080에만 바인딩하고 non-root, read-only filesystem, capability drop을 사용합니다. 내부 FQDN은 별도 Reverse Proxy에서 TLS로 공개하세요.
| Endpoint | 의미 |
|---|---|
GET /healthz | 프로세스가 요청을 처리할 수 있음 |
GET /readyz | DB를 포함한 필수 초기화가 완료됨 |
GET /api/v1/version | 버전·commit·build time 확인 |
4. 최초 관리자 설정
- Bootstrap 로그인
BOOTSTRAP_ADMIN으로 로그인하고 임시 비밀번호를 즉시 변경합니다. - 기능·보존·키 정책
GPU·LLM 관측, 승인 기능, 원시 메트릭 보존일과 개인 키 정책을 실제 운영 범위에 맞게 검토합니다. - Keycloak 연결 테스트
issuer와 client 정보를 입력해 TLS·discovery 필수 항목·응답시간을 확인하고, 저장 뒤 실제 브라우저 로그인으로 code·token·claim 검증을 완료합니다. - JupyterHub 연결 테스트
JupyterHub 관리의 Hub 등록 Drawer에서 현재 URL·TLS·admin API token으로 버전·사용자 조회 권한·응답시간을 확인한 뒤 별도로 저장합니다. - 감사로그 확인
최초 설정과 테스트, 저장 이벤트가 작업자와 결과를 포함하는지 확인합니다.
선택형 모니터링은 초기 OFF
GPU 및 LLM Chat Completions 모니터링은 설치만으로 켜지지 않습니다. OFF 상태에서는 수집 worker, query, 메뉴, KPI가 비활성이고 기존 데이터는 보존됩니다. 수집 오류가 핵심 서비스 상태에 영향을 주지 않습니다.
GPU를 켜기 전
- 각 대상의 Prometheus가 중앙에서 접근 가능해야 합니다.
- NVIDIA DCGM Exporter가 GPU·Pod 식별 메트릭을 노출해야 합니다.
- 관리자 설정의 Prometheus 연결 테스트는
vector(1)쿼리로 API 도달성·인증·TLS와 기본 쿼리 권한만 확인합니다. DCGM 메트릭 존재 여부와 실제 GPU PromQL은 Prometheus에서 별도로 검증하세요.
LLM 사용량을 켜기 전
- API Gateway 또는 Service Mesh가 pod/path/status와 calls counter를 Prometheus에 노출해야 합니다.
- token metric은 선택이며 없으면 호출 건수만 표시됩니다.
- pod name에서 username을 추출하는 정규식을 샘플로 검증합니다.
- 프롬프트·응답 본문이 metric label이나 로그로 들어오지 않는지 확인합니다.
세부 설정은 관리자 가이드를 참고하세요.