서버 설정¶

서버 설정은 환경변수로만 한다. Docker Compose에서는 서버 env 파일(deploy/ 디렉터리의 .env)에 값을 넣고 compose 파일이 그중 정해진 일부를 cctraced 컨테이너에 전달한다.

키는 두 종류다.

Compose 키: 호스트 포트, 바인드 주소, 이미지 태그, 로그 디렉터리 등 컨테이너 구성. cctraced에는 전달되지 않음
서버 변수: cctraced가 직접 읽는 값. Compose는 environment: 블록에 적힌 것만 전달

주석이 달린 템플릿은 deploy/.env.example이다. 서버가 읽는 변수 목록은 컨테이너 안에서 cctraced --help로 확인한다.

$ docker compose --env-file deploy/.env -f deploy/docker-compose.yml exec cctraced cctraced --help

값을 바꾼 뒤에는 컨테이너를 다시 만들어야 적용된다.

$ docker compose --env-file deploy/.env -f deploy/docker-compose.yml up -d

CCTRACE_AI_* 변수와 CCTRACE_SECRETS_KEY는 변경이 진행 중이라 이 문서에서 다루지 않음.

필수¶

키	기본값	의미
`JWT_SECRET`	없음	대시보드 세션 서명 키. 32바이트 이상. 없으면 Compose가 시작 거부, 짧으면 `cctraced`가 `JWT secret must be at least 32 bytes`로, `deploy/.env.example`에 있던 예시 값이면 `JWT_SECRET is a published example value`로 종료
`LOGS_DIR`	없음	`cctraced` 컨테이너의 `/data/logs`에 마운트되는 호스트 디렉터리. 없으면 Compose가 시작 거부. 운영 참조

데이터베이스¶

키	기본값	의미
`DB_PASSWORD`	`cctrace`	`cctrace` DB 슈퍼유저 비밀번호. DB 볼륨 최초 초기화 때만 적용. 첫 시작 전에 지정
`DB_APP_CREDENTIALS`	비어 있음	`cctraced`용 비슈퍼유저 역할의 `<user>:<password>`. 첫 시작 전에 지정(아래 참조)
`DB_PORT`	`5432`	TimescaleDB 호스트 포트. 항상 127.0.0.1에 바인드

Compose는 이 값들로 cctraced의 DATABASE_URL을 만든다. DB_APP_CREDENTIALS가 비어 있으면 cctraced는 cctrace 계정과 DB_PASSWORD로 접속한다.

DB_APP_CREDENTIALS 적용 방식

DB 볼륨이 비어 있는 첫 시작 때 deploy/initdb/10-app-role.sh가 DB_APP_CREDENTIALS의 역할을 NOSUPERUSER NOCREATEROLE NOCREATEDB로 만들고, cctraced는 그 역할로 접속한다. 이 키가 비어 있으면 cctraced는 cctrace 슈퍼유저로 접속하며, 그러면 서버의 결함이 COPY ... FROM PROGRAM을 거쳐 DB 컨테이너 안에서 명령을 실행할 수 있다.

역할 이름은 cctrace(슈퍼유저)일 수 없고 pg_로 시작할 수 없으며, A-Za-z0-9_만 쓸 수 있고, 63바이트 이하여야 한다. 비밀번호는 openssl rand -hex 20처럼 URL에 안전한 문자로만 만든다. compose가 이 값을 연결 URL에 그대로 넣으므로 /, #, ?, %가 들어가면 cctraced가 URL을 해석하지 못하고, 그 해석 오류에 비밀번호 일부가 들어간다.

역할이 만들어지지 않았을 때¶

값의 형식이 틀렸거나 역할을 만들 수 없으면 스크립트는 timescaledb 로그에 [initdb] 접두사로 이유를 출력하고 역할 생성을 건너뛴다. DB 초기화는 그대로 끝난다. cctraced는 여전히 DB_APP_CREDENTIALS의 계정 정보로 접속하므로, 그 이름과 비밀번호의 역할이 생길 때까지 인증에 실패한다.

DB_APP_CREDENTIALS를 비워도 cctraced는 동작하지만 슈퍼유저로 접속하고, 그때 만드는 테이블은 슈퍼유저 소유가 되어 DB가 다음 절의 상황이 된다. cctraced가 한 번도 접속하지 못했다면 DB에 그 객체가 하나도 없으므로, 아래 둘 중 하나로 역할을 추가할 수 있다.

서버 env 파일의 값을 고친다. DB 컨테이너를 다시 만들어 새 값을 보게 하고, ps에서 timescaledb가 (healthy)가 될 때까지 기다린 뒤 그 안에서 스크립트를 다시 실행하고, 나머지 스택을 시작한다.

$ docker compose --env-file deploy/.env -f deploy/docker-compose.yml up -d timescaledb
$ docker compose --env-file deploy/.env -f deploy/docker-compose.yml \
    exec timescaledb sh -c 'PGPASSWORD="$POSTGRES_PASSWORD" sh /docker-entrypoint-initdb.d/10-app-role.sh'
$ docker compose --env-file deploy/.env -f deploy/docker-compose.yml up -d

역할이 만들어지면 스크립트가 [initdb] created <name> (NOSUPERUSER)를 출력한다.

아직 수집한 데이터가 없다면 볼륨을 지우고, 서버 env 파일의 값을 고친 뒤 다시 시작한다. 빈 볼륨에서 스크립트가 다시 실행된다.
```
$ docker compose --env-file deploy/.env -f deploy/docker-compose.yml down -v
$ docker compose --env-file deploy/.env -f deploy/docker-compose.yml up -d
```

이미 사용 중인 DB¶

이 스크립트는 데이터 볼륨이 비어 있을 때만 실행된다. 이미 초기화된 DB에서는 실행되지 않으므로, 그 상태에서 DB_APP_CREDENTIALS를 지정하면 cctraced가 존재하지 않는 역할로 접속한다. 역할을 직접 만드는 것만으로는 부족하다. 슈퍼유저가 이미 만든 객체의 소유권도 그 역할이 가져야 하며, 그렇지 않으면 부팅 마이그레이션이 must be owner로 실패한다. 이 저장소에는 그 전환 도구가 포함되어 있지 않다. DB_APP_CREDENTIALS를 비워 두면 기존 배포는 계속 슈퍼유저로 접속한다.

네트워크¶

키	기본값	의미
`HTTP_BIND`	127.0.0.1	대시보드·REST API 포트의 호스트 주소
`GRPC_BIND`	0.0.0.0	OTLP gRPC 호스트 주소
`OTEL_HTTP_BIND`	0.0.0.0	OTLP HTTP 호스트 주소
`HTTP_PORT`	`8080`	대시보드·REST API 호스트 포트
`GRPC_PORT`	`4317`	OTLP gRPC 호스트 포트
`OTEL_HTTP_PORT`	`4318`	OTLP HTTP 호스트 포트

모두 Compose 키다. 컨테이너 안의 cctraced는 항상 8080, 4317, 4318에서 수신한다. compose 파일이 컨테이너용 HTTP_PORT, GRPC_PORT, HTTP_OTEL_PORT를 이 값으로 고정한다. OTEL_HTTP_PORT(호스트, Compose)와 HTTP_OTEL_PORT(컨테이너, 서버)는 이름이 비슷하지만 다른 키다.

TLS 오버레이를 포함한 전체 표는 포트 참조.

인증과 브라우저 접근¶

키	기본값	의미
`CCTRACE_SETUP_TOKEN`	비어 있음	첫 관리자 생성용 토큰. 비어 있으면 사용자가 없는 동안 `cctraced`가 생성해 로그에 출력. 첫 관리자 생성 후 무효
`COOKIE_SECURE`	`0`	`1`이면 인증 쿠키에 Secure 플래그 강제. 프록시를 거쳐 HTTPS로 대시보드를 제공할 때 지정. TLS 요청이나 `X-Forwarded-Proto: https` 요청은 이 값과 무관하게 Secure 쿠키
`CCTRACE_ALLOWED_ORIGINS`	비어 있음	API 호출을 허용할 다른 호스트·포트의 브라우저 origin 목록(쉼표 구분). 경로 없는 정확한 `scheme://host[:port]` 값. 와일드카드 불가. 비어 있으면 CORS 비활성. 번들 대시보드에는 불필요
`API_KEY`	비어 있음	사용자별 토큰과 함께 허용되는 공유 API 토큰(선택). 비어 있으면 공유 키 비활성, 사용자별 토큰은 계속 동작

동기화 업로드¶

키	기본값	의미
`CCTRACE_MAX_SYNC_BODY_BYTES`	`8388608`(8 MiB)	`POST /api/sync` 요청 본문 최대 크기. 최대 `268435456`(256 MiB). 이보다 크거나, 0 이하이거나, 숫자가 아니면 기본값 유지와 경고 로그

클라이언트는 세션 레코드를 배치로 보내며 크기 기준으로 배치를 나누지 않는다. 한도를 넘는 배치는 HTTP 413으로 거부되고 해당 파일의 동기화는 그 지점에서 멈춘다. 배치가 한도를 넘는다면 한도를 올린다. 서버는 요청 본문 전체를 버퍼링한다. 디코딩에는 요청당 본문 크기의 약 다섯 배 메모리를 쓴다.

이미지와 컨테이너¶

키	기본값	의미
`IMAGE_TAG`	`latest`	실행할 cctrace/cctraced 태그. 로컬 빌드 이미지와 일치 필요
`DB_IMAGE_TAG`	`latest`	실행할 cctrace/timescaledb-pgmq 태그. 로컬 빌드 이미지와 일치 필요
`CONTAINER_PREFIX`	`cctrace`	컨테이너 이름 접두사. 같은 호스트에서 두 번째 스택을 띄울 때만 변경

compose 파일이 전달하지 않는 변수¶

아래 변수는 cctraced가 읽지만 배포된 deploy/docker-compose.yml의 cctraced 서비스에는 적혀 있지 않다. 서버 env 파일에 넣어도 컨테이너에는 영향이 없다. cctraced를 다른 방식으로 실행하거나 서비스의 environment:에 직접 추가할 때 적용된다.

변수	기본값	의미
`OTEL_RETENTION_DAYS`	미설정	OpenTelemetry 이벤트·메트릭 보존 일수. 미설정이면 현재 정책 유지(스키마 기본 90일)
`SESSION_RETENTION_DAYS`	미설정	세션 레코드(대화 내용) 보존 일수. 미설정이면 현재 정책 유지, `0`은 영구 보존
`CCTRACE_USERID_ACCESS_CONTROL`	`true`	세션 데이터의 사용자별 격리. 정확히 `false`일 때만 해제
`CCTRACE_ALLOW_EMPTY_DASHBOARD`	비어 있음	`1`이면 내장 대시보드 없이 시작(API 전용). 없으면 대시보드 없이 빌드한 바이너리는 시작 거부
`DATABASE_URL`	`postgres://cctrace:cctrace@localhost:5432/cctrace?sslmode=disable`	DB 연결 문자열. Compose가 항상 지정(데이터베이스 참조)

보존 기간은 이 변수 없이 대시보드의 Admin > Storage에서 지정할 수 있다. 운영 참조.

모든 키를 한 표로 보려면 서버 환경변수 참조.