Docker Compose 환경변수
FlowKat 서버는 Docker Compose로 7개 서비스를 운영한다. 환경변수는 .env 파일로 관리하며 환경별(dev/prod/aircap/demo) 프리셋을 제공한다.
1. 서비스 구성
| 서비스 | Docker 이미지 | 기술 스택 | 시작 순서 |
|---|---|---|---|
| postgres | flowkat/postgres-ai:16.5 | PostgreSQL 16 + pgvector + pg_partman | 1 |
| valkey | valkey/valkey:9.0-alpine | Valkey 9.0 (Redis-compatible) | 2 |
| collect-server | registry.flowkat.dev/flowkat/collect-server | Java 8 (Corretto) | 3 |
| tx-mining-api | registry.flowkat.dev/flowkat/mining-server | Spring Boot 3.x, JDK 17 | 4 |
| api-server | registry.flowkat.dev/flowkat/api-server | Java 8 (Corretto) | 5 |
| dashboard-server | registry.flowkat.dev/flowkat/dashboard-server | Java 8, Spring Boot | 6 |
| ui-server | registry.flowkat.dev/flowkat/ui-server | Next.js, PM2 | 7 |
2. 핵심 환경변수
파라미터 테이블 (P0~P1)
| 파라미터 | 타입 | 기본값 | conf 키 | 중요도 | 설명 |
|---|---|---|---|---|---|
DEPLOYMENT_ENV | String | production | .env DEPLOYMENT_ENV | 필수 | 배포 환경 (development/production/aircap/demo). |
FLOWKAT_VERSION | String | 5.0.27 | .env FLOWKAT_VERSION | 필수 | Docker 이미지 버전 태그. 프로덕션에서 특정 버전 고정 필수. |
POSTGRES_PASSWORD | String | CHANGE_ME_IN_PRODUCTION | .env POSTGRES_PASSWORD | 필수 | PostgreSQL 비밀번호. 프로덕션에서 반드시 변경. |
NEXTAUTH_URL | String | https://flowkat.example.com | .env NEXTAUTH_URL | 필수 | 인증 콜백 URL. 실제 접속 URL과 일치 필수. |
NETWORK_MODE_COLLECT | String | bridge | .env NETWORK_MODE_COLLECT | 핵심 | Collect Server 네트워크 모드. docker-compose 기본값은 bridge. prod .env에서 host로 오버라이드한다. |
RESTART_POLICY | String | unless-stopped | .env RESTART_POLICY | 핵심 | Docker restart 정책. 프로덕션 .env에서 always로 오버라이드. |
공통
네트워크
| 환경변수 | 기본값 (prod) | 설명 |
|---|---|---|
NETWORK_MODE_COLLECT | host | Collect Server 네트워크 모드. prod에서 host 모드 사용(라이선스 검증). |
COLLECT_POSTGRES_HOST | 127.0.0.1 | XLog Plugin DB 접속 IP. bridge 모드에서는 172.17.0.1. |
데이터베이스
| 환경변수 | 기본값 (prod) | 설명 |
|---|---|---|
POSTGRES_DB | txmining | PostgreSQL 데이터베이스명. |
POSTGRES_USER | txmining | PostgreSQL 사용자명. |
POSTGRES_PASSWORD | CHANGE_ME_IN_PRODUCTION | 프로덕션에서 반드시 변경. |
인증/보안
| 환경변수 | 기본값 (prod) | 설명 |
|---|---|---|
NEXTAUTH_URL | https://flowkat.example.com | 인증 콜백 URL. 실제 접속 URL과 일치 필수. |
USE_SECURE_COOKIES | true | HTTPS 환경에서 true. HTTP 환경에서는 false. |
AUTH_TRUST_HOST | true | 리버스 프록시 뒤에서 호스트 신뢰. |
CORS_ORIGINS | https://flowkat.example.com | CORS 허용 도메인. 콤마 구분 복수 지정 가능. |
TX-Mining
| 환경변수 | 기본값 (prod) | 설명 |
|---|---|---|
TX_MINING_ENABLED | (미설정) | TX-Mining 기능 활성화 여부. |
TXMINING_PROFILE | prod | Spring Boot 프로파일. |
SENTRY_ADDRESS | http://127.0.0.1:6300 | 알림 콜백 URL. |
3. JVM 힙 설정 (환경별)
| 서비스 | Development | Production | Demo |
|---|---|---|---|
| collect-server | -Xmx1g -Xms512m | -Xmx2g -Xms2g | -Xmx512m -Xms256m |
| api-server | -Xmx512m -Xms256m | -Xmx1g -Xms1g | -Xmx256m -Xms128m |
| dashboard-server | -Xmx1g -Xms512m | -Xmx2g -Xms1g | -Xmx512m -Xms256m |
| tx-mining-api | -Xmx512m -Xms256m | -Xmx1g -Xms512m | -Xmx512m -Xms256m |
| 최소 총 메모리 | ~3GB | ~7GB | ~1.5GB |
4. 환경별 차이점
| 항목 | Development | Production | Aircap |
|---|---|---|---|
| NETWORK_MODE_COLLECT | bridge | host | host |
| COLLECT_POSTGRES_HOST | 172.17.0.1 | 127.0.0.1 | 127.0.0.1 |
| USE_SECURE_COOKIES | false | true | false |
| POSTGRES_PASSWORD | txmining | CHANGE_ME_IN_PRODUCTION | CHANGE_ME_IN_PRODUCTION |
| NEXTAUTH_URL | http://localhost:6300 | https://flowkat.example.com | http://{서버IP}:6300 |
5. 설치 절차
# 1. 릴리즈 번들 압축 해제
tar -xzf flowkat-release-5.0.27.tar.gz
# 2. 이미지 로드
sh load-images.sh
# 3. 환경 설정 (대화형)
sh flowkat-env-setup.sh
# 4. 볼륨 초기화
sh flowkat-volume-manager.sh init
# 5. 서비스 시작
sh start-all.sh
# 6. 헬스체크
sh check-collect-server.sh
sh check-tx-mining.sh
6. 주의사항
| 상황 | 주의 내용 |
|---|---|
| POSTGRES_PASSWORD | 프로덕션에서 반드시 강력한 패스워드로 변경한다. 기본값은 보안 취약. |
| NETWORK_MODE_COLLECT=host | 호스트 네트워크 모드에서는 Collect Server가 호스트의 모든 포트에 직접 바인딩된다. 방화벽 설정 확인 필수. |
| bridge 모드 XLog Plugin | bridge 모드에서 XLog Plugin이 PostgreSQL에 접속하려면 Docker 게이트웨이 IP(172.17.0.1)를 사용한다. |
| 이미지 버전 고정 | 프로덕션에서는 FLOWKAT_VERSION을 특정 버전으로 고정한다. latest 사용 금지. |
| net.ipv4.ip_forward | Docker bridge 네트워크는 net.ipv4.ip_forward=1이 필수이다. sysctl -w로 임시 설정한 경우 서버 재부팅 시 0으로 초기화되어 컨테이너 간 통신이 불가해진다. /etc/sysctl.conf에 net.ipv4.ip_forward=1을 영구 등록해야 한다. NetworkManager나 보안 강화 스크립트가 값을 덮어쓸 수 있으므로 grep -r "ip_forward" /etc/sysctl.d/로 간섭 여부도 확인한다. |
| POSTGRES_USER_ID 권한 | postgres와 valkey 컨테이너는 user: ${POSTGRES_USER_ID:-1000:1000}으로 실행된다. 일반 계정(non-root)으로 Docker를 기동할 때 볼륨 디렉토리의 UID가 컨테이너 실행 UID와 불일치하면 Permission denied 에러가 발생한다. .env에서 POSTGRES_USER_ID를 실제 기동 계정의 UID:GID로 맞추거나 chown <UID>:<GID> volumes/mining-server/postgres-data volumes/mining-server/valkey-data로 권한을 조정한다. |
7. 관련 문서
- 수집 서버 파라미터: 14.collect-server.md
- 대시보드/API 서버: 15.dashboard-server.md
- 네트워크/포트: 17.network-ports.md
- 아키텍처 초안: architecture-draft.md