SSD Nodes Learn Hosting plans →
가이드 Matt Connor작성자 Matt Connor

Docker로 VPS에 Zitadel 자체 호스팅하기

Zitadel 자체에는 약 512MB RAM이 필요합니다. 한 대의 VPS에서 PostgreSQL, masterkey, TLS, SMTP와 백업을 설정하고 업그레이드가 데이터베이스에 미치는 영향까지 확인합니다.

VPS에서 Zitadel을 직접 호스팅하기 위한 준비 사항

VPS에서 Zitadel을 직접 호스팅하려면 Docker 호스트, 해당 서버를 가리키는 공용 DNS 이름, PostgreSQL, 그리고 이들을 모두 구동할 충분한 CPU와 RAM이 필요합니다. Zitadel의 프로덕션 가이드에 따르면 애플리케이션 자체는 약 512 MB의 RAM과 1개 미만의 CPU 코어를 사용합니다. 데이터베이스와 비밀번호 해싱 작업이 늘어날수록 자원 소모가 증가합니다. Zitadel은 ID 공급자(Identity Provider)입니다. OIDC(OpenID Connect) 및 SAML(Security Assertion Markup Language)을 통해 토큰을 발행하므로, 다른 서비스들이 자체적으로 사용자 목록을 관리할 필요가 없습니다. 설치 과정은 curl와 docker compose up로 구성됩니다. 운영의 성패를 결정짓는 핵심 요소는 마스터 키, 데이터베이스 사용자, SMTP(Simple Mail Transfer Protocol), 백업, 그리고 첫 번째 업그레이드입니다.

이하의 모든 내용은 Ubuntu 24.04, Docker Engine 24 이상, Compose 플러그인 버전 2.24.4 이상을 사용하며, auth.example.com와 같은 도메인이 이미 서버를 가리키고 있다는 가정하에 작성되었습니다. TLS 오버레이는 !override를 사용하며, 이는 해당 Compose 버전을 요구합니다.

Zitadel은 어느 정도 규모의 VPS가 필요한가?

Zitadel 문서의 Compose 퀵스타트에서는 2 GB의 RAM을 요구합니다. 이 수치는 퀵스타트만을 위한 것입니다. Zitadel의 운영 가이드에는 다른 수치가 명시되어 있습니다.

차트Zitadel's own published sizing guidance, October 2026
이 차트의 데이터
[
  {
    "config": "Zitadel itself, under 1 core",
    "cpu_cores": 0.5,
    "ram_gb": 0.5
  },
  {
    "config": "HA node, reduced setup",
    "cpu_cores": 4,
    "ram_gb": 8
  },
  {
    "config": "HA node, logs and metrics on",
    "cpu_cores": 4,
    "ram_gb": 16
  }
]

이는 운영 중인 서버에서 측정한 값이 아니라 권장 사양입니다. 이 수치를 문제의 규모를 파악하는 지표로 활용하십시오. Zitadel 프로세스 자체는 작습니다. 가이드에서는 약 0.5 GB의 RAM을 할당하고 CPU 코어 1개 미만으로도 실행 가능하다고 설명합니다. CPU 코어가 필요한 이유는 의도적으로 느리게 설계된 비밀번호 해싱 작업 때문입니다. 로그인 요청이 몰리면 CPU 사용량이 급증하므로, 가이드에서는 4개의 CPU 코어를 확보할 것을 권장합니다. 나머지 절반은 PostgreSQL이 차지합니다. 같은 가이드에서는 초당 100건의 요청마다 약 1개의 코어와 코어당 4 GB의 RAM을 예산으로 책정합니다.

더 큰 규모의 두 행은 단일 서버 기준이 아닙니다. 최소한의 고가용성 구성을 위해 가이드에서는 각 4 코어와 16 GB RAM을 갖춘 3개 노드 클러스터를 권장합니다. 로그 수집 및 메트릭 기능을 제외하면 노드당 약 4 코어와 8 GB RAM으로 줄일 수 있다고 명시합니다. 단일 노드에 대한 권장 사양은 별도로 언급하지 않습니다.

따라서 2 GB VPS로도 이 스택을 시작할 수는 있지만, 이는 실제 트래픽이 발생했을 때 가이드가 데이터베이스 하나에만 책정하는 예산보다 훨씬 낮은 수준입니다. 로그인은 다른 모든 서비스가 의존하는 서비스입니다. 로그인이 중단되면 해당 서비스를 신뢰하는 모든 서비스에 접근할 수 없게 됩니다. 가이드에서 제시하는 데이터베이스 및 해싱 예산이 인증 서비스에 투자하기에 과도하다고 판단하는 것은 합리적인 결정이며, 마이그레이션 이후보다 지금 결정하는 것이 비용 면에서 훨씬 유리합니다. Keycloak, Authentik, Zitadel 비교 문서에서 각 서비스의 메모리 소모량과 운영 부담을 다루고 있으며, 더 작은 서버에서는 보통 자체 호스팅 Authentik 서버를 대안으로 선택합니다.

스택 확보 및 버전 고정

mkdir zitadel-compose && cd zitadel-compose
curl -fsSLO https://raw.githubusercontent.com/zitadel/zitadel/main/deploy/compose/docker-compose.yml
curl -fsSLO https://raw.githubusercontent.com/zitadel/zitadel/main/deploy/compose/.env.example
cp .env.example .env
chmod 600 .env

이 파일은 실제로 실행할 4개의 서비스를 정의합니다. Traefik은 리버스 프록시 역할을 하며, 경로별로 라우팅을 수행하고 아래의 오버레이 설정을 통해 TLS(Transport Layer Security)를 종료합니다. zitadel-api은 포트 8080에서 동작하는 Go 바이너리입니다. zitadel-login은 /ui/v2/login에서 제공되는 로그인 인터페이스입니다. postgres은 모든 데이터를 저장합니다. Redis 캐시와 OpenTelemetry 수집기는 동일한 파일 내에 Compose 프로필 뒤에 숨겨져 있으며, 사용자가 활성화하기 전까지는 실행되지 않습니다.

아직 docker compose up을 실행하지 마십시오. 첫 실행 시 인스턴스가 생성되며, 아래의 몇몇 설정은 이후에 변경하려면 추가 작업이 필요합니다.

복사한 .env는 자체 이미지 태그를 고정합니다:

ZITADEL_VERSION=v4.16.0
TRAEFIK_IMAGE=traefik:v3.7.7
POSTGRES_IMAGE=postgres:17.10-alpine

현재 v4 릴리스는 2026년 11월 13일에 출시된 v4.20.3이며, 배포 파일에 고정된 버전보다 4개의 마이너 버전이 앞서 있습니다. v4.20.0 이전 릴리스인 2026년 10월 15일자 v4.19.5는 Zitadel 기술 권고 A-10018이 적용된 첫 번째 버전입니다. v1 및 v2 API의 영향받는 목록 엔드포인트에 기본 및 최대 제한이 적용되었으므로, 제한 없이 목록을 요청하던 클라이언트는 더 이상 모든 결과를 가져올 수 없으며 페이지네이션을 사용해야 합니다. 최대치를 초과하는 요청은 거부됩니다. v4.20.0을 포함한 이후의 모든 릴리스에는 이 변경 사항이 포함되어 있습니다. ZITADEL_VERSION를 실행하려는 버전으로 설정하고, 최신 버전을 무작정 추적하기보다 v4 라인에 머무르십시오. 버전을 직접 선택할 경우 v4.18.0은 건너뛰십시오. 릴리스 노트에 따르면 해당 버전에서는 설정 단계가 실패하므로 v4.19.0을 사용해야 합니다. 위에서 언급한 curl은 main 브랜치에서 docker-compose.yml을 가져오는데, 이 브랜치는 아무것도 고정되어 있지 않으므로 두 파일의 복사본을 git 저장소에 커밋하십시오. 그렇지 않으면 다음 달에 새로운 서버에서 동일한 명령을 실행할 때 다른 파일이 생성되어 무엇이 변경되었는지 알 수 없게 됩니다.

.env의 LOGIN_SESSION_COOKIE_SECRET을 openssl rand -base64 32로 생성한 임의의 값으로 교체하십시오. 로그인 UI는 이 값을 사용하여 세션 쿠키에 서명하며, v4.19.5 릴리스 노트는 예제 값을 그대로 사용하는 것에 대해 명시적으로 경고하고 있습니다.

Postgres에 전용 사용자와 실제 비밀번호 할당하기

제공되는 .env는 Zitadel을 PostgreSQL의 슈퍼유저로 연결하며, 비밀번호는 postgres입니다:

POSTGRES_ADMIN_USER=postgres
POSTGRES_ADMIN_PASSWORD=postgres
ZITADEL_DATABASE_POSTGRES_DSN=postgresql://postgres:postgres@postgres:5432/zitadel?sslmode=disable

보안 강화 단계에는 함정이 하나 있습니다. Zitadel 문서에서는 POSTGRES_ZITADEL_PASSWORD을 .env에 추가하라고 안내하지만, 기본 docker-compose.yml은 해당 변수를 읽지 않으므로 설정해도 아무런 변화가 없습니다. POSTGRES_ADMIN_PASSWORD만 단독으로 변경하면 비밀번호가 DSN(데이터 소스 이름) 문자열 내부에 그대로 기록되어 있기 때문에 오히려 연결이 끊어집니다. DSN은 Zitadel의 연결 방식을 결정하는 행입니다.

.env.example의 주석에는 명확히 설명되어 있습니다. DSN이 설정되면 Zitadel은 해당 사용자를 직접 사용하며 권한이 제한된 사용자를 별도로 생성하지 않으므로, 첫 실행 전에 역할이 존재해야 합니다. 역할에 사용할 비밀번호를 생성하고, Postgres를 시작하기 전에 .env에서 POSTGRES_ADMIN_PASSWORD을 별도의 임의 비밀번호로 설정한 뒤, Postgres를 단독으로 시작하여 역할을 생성하십시오. Postgres 이미지는 빈 데이터 디렉터리를 초기화할 때만 관리자 비밀번호를 적용합니다. 이후에 .env을 변경해도 기존 데이터베이스 비밀번호는 갱신되지 않습니다.

tr -dc A-Za-z0-9 </dev/urandom | head -c 32; echo

docker compose --env-file .env -f docker-compose.yml up -d postgres

docker compose --env-file .env -f docker-compose.yml exec -T postgres \
  psql -U postgres -d postgres <<'SQL'
CREATE ROLE zitadel LOGIN PASSWORD 'the-password-you-generated';
ALTER DATABASE zitadel OWNER TO zitadel;
SQL

해당 psql 호출은 공식 Postgres 이미지가 신뢰하는 로컬 소켓을 통해 컨테이너 내부에서 실행되므로 비밀번호를 묻지 않습니다. 중요한 것은 소유권입니다. Zitadel의 초기화 단계는 자체 스키마(eventstore, projections, system)와 테이블을 생성합니다. 데이터베이스 소유권은 해당 역할에 스키마를 부트스트랩하는 데 필요한 CREATE 권한을 부여합니다. PostgreSQL 15에서 public 스키마의 CREATE 권한이 변경된 것은 별개의 문제이며, Zitadel의 스키마 부트스트랩이 실패한다는 의미는 아닙니다.

이제 DSN이 새로운 역할을 가리키도록 설정하고, Postgres를 시작하기 전에 설정했던 관리자 비밀번호를 유지하십시오:

POSTGRES_ADMIN_PASSWORD=a-32-character-random-string
ZITADEL_DATABASE_POSTGRES_DSN=postgresql://zitadel:the-password-you-generated@postgres:5432/zitadel?sslmode=disable

sslmode=disable는 비공개 Compose 네트워크에서 데이터베이스 연결을 암호화하지 않은 상태로 둡니다. 해당 포트는 호스트에 공개되지 않습니다. Zitadel 데이터베이스 가이드는 프로덕션 환경의 데이터베이스 연결에 TLS를 사용할 것을 권장합니다. 첫 번째 전체 시작 후, 역할이 데이터의 소유권을 정상적으로 가졌는지 확인하십시오:

docker compose exec -T postgres psql -U zitadel -d zitadel -c '\dn'

이 명령을 실행하면 eventstore 스키마, projections 스키마, system 스키마가 나열되어야 합니다. 해당 스키마들이 보이지 않는다면 초기화 단계가 그 지점까지 진행되지 않은 것이며, API 컨테이너 로그에서 이유를 확인할 수 있습니다.

마스터 키와 분실 시의 대가

Zitadel은 ID 공급자 자격 증명, SMTP 비밀번호, 일회용 비밀번호(OTP) 시드, 머신 키와 같은 비밀 정보를 저장하기 전에 암호화합니다. 마스터 키는 이 모든 정보를 복호화하는 열쇠입니다. 이 키는 정확히 32바이트이며, 문서에서는 그 결과를 명확히 경고합니다. 마스터 키를 변경하면 암호화된 데이터에 접근할 수 없게 됩니다.

키를 생성하여 .env의 자리 표시자 줄을 교체하십시오:

tr -dc A-Za-z0-9 </dev/urandom | head -c 32; echo

ZITADEL_MASTERKEY=MasterkeyNeedsToHave32Characters 줄은 새로 추가하지 말고 수정하십시오. Docker Compose는 중복된 키가 있을 경우 마지막 정의를 사용하므로 추가하는 방식도 작동은 하지만, 마스터 키 줄이 두 개 포함된 파일은 나중에 파일을 읽는 사람에게 혼란을 줄 수 있습니다.

이제 이 키가 어디에 위치하는지 고려해야 합니다. Compose 파일은 다음과 같이 API 컨테이너를 시작합니다:

command: start-from-init --masterkey "${ZITADEL_MASTERKEY}"

따라서 마스터 키는 컨테이너 명령줄에 위치하게 되며, docker inspect을 통해 Docker 소켓에 접근할 수 있는 모든 사용자가 이를 확인할 수 있습니다. 관리자가 한 명뿐인 VPS 환경에서는 허용 가능한 수준이며, .env의 파일 모드가 디스크상의 키를 보호합니다. 만약 이 방식이 허용되지 않는다면, 키를 파일로 마운트하고 --masterkeyFile /run/secrets/zitadel-masterkey를 대신 사용하여 프로세스 인자에 값이 노출되지 않도록 하십시오.

첫 번째 시작 전에 마스터 키를 비밀번호 관리자에 복사해 두십시오. 마스터 키는 데이터베이스 덤프에 포함되지 않으므로, 다른 마스터 키로 복원된 덤프는 자신의 비밀 정보를 읽을 수 없는 인스턴스를 생성하게 됩니다. 덤프를 보관하는 저장소와는 별도의 장소에 키를 보관하십시오. 그래야 백업이 탈취되더라도 암호화된 데이터와 이를 복호화할 키가 동시에 유출되는 상황을 방지할 수 있습니다.

첫 시작 전에 외부 도메인 설정하기

ZITADEL_DOMAIN은 .env 내의 ZITADEL_EXTERNALDOMAIN에 반영되며, 사용자가 직접 입력하는 주소입니다. Zitadel은 이 값을 바탕으로 OIDC 발급자, 로그인 인터페이스 기본 URI, SAML 엔드포인트, 최초 관리자 로그인 이름을 결정하므로 단순한 이름 이상의 의미를 갖습니다.

ZITADEL_DOMAIN=auth.example.com
ZITADEL_EXTERNALPORT=443
ZITADEL_EXTERNALSECURE=true

Zitadel은 Host 헤더를 통해 사용자가 어떤 인스턴스에 접근하는지 식별합니다. 해당 헤더가 Zitadel에 등록된 도메인과 일치하지 않으면 모든 요청에 대해 동일한 응답이 반환됩니다.

ID=QUERY-1kIjX Message=Instance not found

이 오류가 발생하면 다음 두 가지를 확인하십시오. ZITADEL_DOMAIN이 현재 접속 중인 도메인 이름과 다르거나, 앞단에 위치한 프록시가 Host을 업스트림 주소로 재작성하고 있을 가능성이 있습니다. 도메인 이름 대신 서버의 IP 주소로 직접 접속하는 경우에도 동일한 오류가 발생합니다.

이 값들은 나중에 변경할 수 있습니다. 다만 Zitadel이 변경 사항을 적용하려면 설정 단계를 다시 실행해야 하며, 이미 등록된 모든 애플리케이션은 기존의 리다이렉트 URI를 그대로 유지합니다. 따라서 처음부터 최종 도메인 이름을 설정하는 것이 나중에 변경하는 것보다 훨씬 효율적입니다.

Let's Encrypt 오버레이로 TLS 종료하기

공용 도메인의 경우 Zitadel의 Let's Encrypt 오버레이를 추가합니다. 이 오버레이는 Traefik을 ACME(자동 인증서 관리 환경) HTTP 챌린지 방식으로 전환하며, 게시된 포트를 80번과 443번으로 대체합니다. 따라서 서버 내의 다른 어떤 서비스도 해당 포트를 점유해서는 안 됩니다.

curl -fsSLO https://raw.githubusercontent.com/zitadel/zitadel/main/deploy/compose/docker-compose.mode-letsencrypt.yml
echo 'LETSENCRYPT_EMAIL=ops@example.com' >> .env

또한 이 오버레이는 API 컨테이너에 ZITADEL_EXTERNALPORT: 443 및 ZITADEL_EXTERNALSECURE: true을 설정합니다. 이를 통해 공개 URL과 Zitadel이 자체적으로 생성하는 URL이 일치하게 됩니다. HTTP 챌린지는 A 레코드가 없으면 실패하므로, 시작하기 전에 반드시 A 레코드가 도메인으로 확인되어야 합니다.

이미 nginx나 로드 밸런서에서 TLS를 종료하고 있다면, 대신 docker-compose.mode-external-tls.yml을 사용하고 TRAEFIK_TRUSTED_IPS에 프록시가 요청을 보내는 대역을 설정하십시오. Traefik은 해당 목록에 포함된 주소에서 보낸 X-Forwarded-* 헤더만 신뢰합니다. 이 오버레이는 Zitadel의 외부 URL과 로그인 URL을 HTTPS로 명시적으로 설정합니다.

업스트림 프록시는 Zitadel이 엄격하게 요구하는 두 가지 작업을 수행해야 합니다. 첫째, API가 gRPC이므로 백엔드와 HTTP/2로 통신해야 합니다. 둘째, Host를 X-Forwarded-Proto: https와 함께 변경 없이 그대로 전달해야 합니다. 이 Compose 스택을 사용할 경우, nginx 설정은 다음과 같은 형태를 갖습니다.

server {
    listen 443 ssl;
    http2 on;
    ssl_certificate     /etc/certs/selfsigned.crt;
    ssl_certificate_key /etc/certs/selfsigned.key;
    location /ui/v2/login {
        proxy_pass http://YOUR_LOGIN_UPSTREAM:3000;
        proxy_set_header Host $host;
        proxy_set_header X-Forwarded-Proto https;
    }
    location / {
        grpc_pass grpc://YOUR_API_UPSTREAM:8080;
        grpc_set_header Host $host;
        grpc_set_header X-Forwarded-Proto https;
    }
}

업스트림 플레이스홀더를 nginx가 접근할 수 있는 주소로 교체하십시오. 443번이 아닌 다른 포트에서 Zitadel을 서비스하는 경우, grpc_set_header Host $host:$server_port;을 사용하여 포트 정보가 헤더와 함께 전달되도록 하십시오. 나머지는 일반적인 가상 호스트 설정과 동일하며, nginx 리버스 프록시 설정의 줄 단위 설명에서 Zitadel과 무관한 일반적인 설정 부분을 다룹니다.

첫 번째 관리자와 비밀번호 변경 강제

처음 시작하면 인스턴스 1개, 조직 1개, 사람 관리자 1명이 생성된다. 로그인 이름은 zitadel-admin@, zitadel., 외부 도메인을 이어 붙인 값이다. 따라서 ZITADEL_DOMAIN=auth.example.com를 사용하면 다음과 같다.

zitadel-admin@zitadel.auth.example.com

직접 설정하지 않았다면 비밀번호는 Password1!다. Zitadel의 기본 동작은 첫 로그인 시 비밀번호를 변경하도록 강제하는 것이지만, 제공된 compose 파일은 이 기본값을 덮어쓴다.

ZITADEL_FIRSTINSTANCE_ORG_HUMAN_PASSWORDCHANGEREQUIRED: false

해당 줄은 .env에서 읽지 않고 docker-compose.yml에 하드코딩되어 있다. 따라서 직접 만든 작은 overlay에 원하는 값을 지정한다. 파일 이름은 docker-compose.local.yml로 지정한다.

services:
  zitadel-api:
    environment:
      ZITADEL_FIRSTINSTANCE_ORG_HUMAN_EMAIL_ADDRESS: you@example.com
      ZITADEL_FIRSTINSTANCE_ORG_HUMAN_PASSWORD: "a-long-temporary-password"
      ZITADEL_FIRSTINSTANCE_ORG_HUMAN_PASSWORDCHANGEREQUIRED: "true"

Compose는 -f flag 없이 실행할 때만 docker-compose.override.yml를 자동으로 로드한다. Zitadel 가이드의 모든 명령은 -f을 전달하므로 이 동작이 비활성화된다. 계속 늘어나는 flag 목록을 반복해서 입력하는 대신, .env에 파일 목록을 고정한다.

COMPOSE_FILE=docker-compose.yml:docker-compose.mode-letsencrypt.yml:docker-compose.local.yml

이제 시작한다.

docker compose pull
docker compose up -d --wait

--wait은 healthcheck가 통과할 때까지 명령을 대기시킨다. API 컨테이너가 계속 해당 상태에 도달하지 못하면 Compose가 dependency failed to start: container zitadel-zitadel-api-1 is unhealthy와 함께 중지되고, docker compose logs zitadel-api에 원인이 기록된다. 컨테이너 이름은 project 이름을 기반으로 정해진다. 제공된 compose 파일은 최상위 name: zitadel으로 이 이름을 직접 설정하므로 디렉터리 이름은 사용되지 않는다. 처음 시작할 때는 masterkey 길이 또는 database DSN이 원인인 경우가 많다.

https://auth.example.com/ui/console에서 로그인하고 비밀번호를 변경한다. 그런 다음 다른 항목을 만들기 전에 해당 계정에 두 번째 인증 요소를 활성화한다. 모든 ZITADEL_FIRSTINSTANCE_* 값은 첫 번째 인스턴스를 생성하는 동안에만 적용된다. 인스턴스가 생성된 뒤에는 해당 값을 수정해도 아무런 효과가 없다.

SMTP가 작동하지 않을 때 비밀번호 재설정이 아무런 동작도 하지 않는 이유

메일을 발송할 수 없는 ID 공급자는 몇 주 동안이나 문제가 드러나지 않은 채 방치될 수 있습니다. Zitadel은 사용자 초대, 주소 확인, 비밀번호 재설정 링크, 일회용 코드, 도메인 소유권 주장 알림을 위해 이메일을 발송합니다. SMTP 공급자가 설정되지 않은 상태에서 콘솔은 작업을 완료된 것으로 보고하지만, 알림 메시지는 전송할 곳이 없는 알림 처리 프로세스로 넘어갑니다. v4.20.0 버전에서 알림은 기본적으로 레거시 모드(LegacyEnabled: true)를 사용하며, 이는 병렬 워커의 MaxAttempts: 3 및 MaxTtl: 5m 설정을 무시합니다. 해당 값들은 기본 알림 재시도 동작을 설명하지 않습니다. 링크를 기다리는 사용자에게는 아무런 알림도 전달되지 않습니다.

콘솔의 https://auth.example.com/ui/console/settings에 있는 인스턴스 설정에서 SMTP를 구성하십시오. SMTP 공급자 양식은 발신자 이메일 주소, 발신자 이름, 호스트 및 포트, 사용자, SMTP 비밀번호, TLS 토글 설정을 요구합니다. 저장하기 전에 양식 내의 테스트 버튼을 사용하십시오. 실제 메시지가 발송되므로 메일 도착 여부를 즉시 확인할 수 있습니다. 공급자를 활성화해야 Zitadel이 해당 설정을 사용하여 메일을 발송합니다.

ZITADEL_DEFAULTINSTANCE_SMTPCONFIGURATION_SMTP_HOST 및 관련 환경 변수들도 존재합니다. 이 변수들은 인스턴스가 생성될 때 적용됩니다. 이미 실행 중인 스택에는 영향을 주지 않으므로, 기존 인스턴스의 경우 콘솔에서 설정하는 것이 올바른 방법입니다.

VPS에서 메일을 발송할 때 자주 실패하는 두 가지 사항을 확인하십시오. 릴레이를 선택하기 전에 공급자의 아웃바운드 SMTP 정책을 확인하십시오. DigitalOcean은 기본적으로 Droplet에서 25, 465, 587번 포트를 차단하므로, 587번 포트가 모든 환경에서 통용되는 해결책은 아닙니다. 공급자가 허용하는 포트에서 인증된 릴레이를 사용하십시오. 또한 발신 도메인에 대해 SPF(Sender Policy Framework) 및 DKIM(DomainKeys Identified Mail) 레코드를 게시하십시오. 그렇지 않으면 재설정 링크가 스팸 메일함으로 분류되어, 사용자 입장에서는 메일이 발송되지 않은 것처럼 보일 수 있습니다.

v4.20.0 버전에서 아웃바운드 SMTP TLS 연결은 eMudhra 중간 CA를 통해 손상된 인증서 체인을 거부합니다. 영향을 받는 릴레이는 인증서를 교체해야 합니다.

사용자를 초대하기 전에 먼저 테스트하십시오. 임시 사용자를 생성하고 비밀번호 재설정을 요청한 뒤 메일이 도착하는지 확인하십시오. 메일이 도착하지 않는다면 docker compose logs -f zitadel-api에서 SMTP 실패 원인을 확인할 수 있습니다. SMTP 비밀번호는 데이터베이스에 암호화되어 저장되며, 이는 마스터키가 보호하는 항목 중 하나입니다.

Postgres와 masterkey를 별도로 백업하기

Zitadel의 모든 정보는 PostgreSQL에 저장됩니다. 이를 복호화하는 것은 masterkey입니다. 이 둘을 서로 다른 두 곳에 백업하십시오.

먼저 덤프를 생성합니다:

sudo install -d -m 700 /srv/zitadel-backups
docker compose exec -T postgres \
  pg_dump -U postgres -Fc zitadel > "/srv/zitadel-backups/zitadel-$(date +%F).dump"

-Fc은 사용자 지정 형식으로, 내보내는 과정에서 압축을 수행하며 pg_restore가 선택적으로 읽을 수 있습니다. exec -T은 터미널을 분리하는데, 이는 터미널이 연결되지 않은 cron에서 실행할 때 중요합니다.

그다음 restic을 사용하여 해당 디렉터리를 외부 저장소로 전송합니다. restic은 데이터를 암호화하고 중복을 제거합니다:

export RESTIC_REPOSITORY="sftp:backup@backup.example.com:/srv/restic/zitadel"
export RESTIC_PASSWORD_FILE=/root/.restic-password
restic init
restic backup /srv/zitadel-backups
restic forget --keep-daily 7 --keep-weekly 4 --keep-monthly 6 --prune

restic init는 첫날에만 한 번 실행합니다. 덤프와 마지막 두 명령어를 /usr/local/bin/zitadel-backup.sh에 넣고 매일 밤 실행하십시오:

0 3 * * * /usr/local/bin/zitadel-backup.sh

.env과 사용하는 모든 compose 파일을 git으로 백업하십시오. masterkey는 이 모든 규칙의 예외입니다. masterkey는 비밀번호 관리자에 저장해야 하며, restic 저장소가 아닌 다른 두 번째 위치에 보관해야 합니다. 데이터베이스와 복호화 키를 함께 보관하는 아카이브는 암호화된 시스템의 백업으로서 의미가 없기 때문입니다.

복원해보지 않은 백업은 추측일 뿐입니다. 동일한 서버의 임시 데이터베이스에 복원하여 확인하십시오:

docker compose exec -T postgres createdb -U postgres zitadel_restore_test
docker compose exec -T postgres pg_restore -U postgres -d zitadel_restore_test \
  < /srv/zitadel-backups/zitadel-2026-08-21.dump
docker compose exec -T postgres psql -U postgres -d zitadel_restore_test -c '\dt eventstore.*'
docker compose exec -T postgres dropdb -U postgres zitadel_restore_test

eventstore 스키마의 테이블 목록이 보인다면 덤프가 정상입니다. 스키마가 존재하지 않는다는 오류가 발생한다면 백업이 잘못된 것이며, 다행히도 아무런 피해가 없는 날에 이를 발견한 것입니다. Compose 스택 백업 및 업그레이드 일반 패턴이 거의 그대로 적용되며, masterkey를 동일한 아카이브에 포함하지 않는 것만이 Zitadel에서 특별히 주의할 점입니다.

인스턴스 손실 없이 Zitadel 업그레이드하기

업그레이드는 .env의 버전을 올린 후 다음 두 명령을 실행하는 과정입니다:

docker compose pull
docker compose up -d --wait

두 번째 명령을 실행하기 전에 해당 명령이 수행하는 작업을 이해하십시오. 컨테이너의 명령은 start-from-init이며, 이는 서비스 시작 전 초기화 및 설정 단계를 실행합니다. 설정 단계는 데이터베이스 마이그레이션을 포함합니다. 따라서 버전 업데이트 시 컨테이너가 시작되면서 라이브 데이터베이스에 대해 스키마 마이그레이션이 자동으로 실행되며, 그동안 --wait는 상태 확인(healthcheck)이 완료될 때까지 대기합니다. 이것이 바로 앞서 언급한 복원 테스트가 선택 사항이 아닌 이유입니다.

업그레이드 직전에 최신 덤프를 생성하십시오. 어젯밤의 덤프는 현재 상태와 다를 수 있습니다.

v4.20.3의 경우, 진행 중인 외부 ID 공급자 로그인은 재시작되어야 하며, 사용되지 않은 Login V1 인증 코드는 한 번 거부됩니다. 사용자 지정 로그인 UI는 OIDC 또는 SAML 요청을 완료하기 위해 session.link 권한이 필요합니다. 업그레이드 전에 해당 서비스 사용자에 IAM_LOGIN_CLIENT 권한을 부여하십시오. 배포된 Login V2 서비스 사용자는 이미 해당 역할을 가지고 있습니다. 세션 API 비밀번호 검사는 이제 사용자의 조직 로그인 정책을 강제하므로, 사용자 이름/비밀번호 로그인을 비활성화한 조직은 사용자를 해당 ID 공급자로 리다이렉트해야 합니다.

메이저 버전을 건너뛰지 마십시오. v3에서 v4로 이동하기 전에 먼저 v3.4.1 이상으로 업데이트하십시오. v4는 OIDC 웹 키를 필수로 요구하며 기존 레거시 서명 경로를 제거합니다. 따라서 v3 인스턴스에서 웹 키를 활성화한 적이 없다면, 업그레이드 후 기존 레거시 키로 서명된 토큰은 더 이상 검증할 수 없습니다. Zitadel 기술 권고 A-10017에 따르면 기존 JWT 액세스 토큰 및 ID 토큰이 즉시 무효화될 수 있으며 사용자가 다시 로그인해야 할 수 있습니다. 해결책은 v3.4.1 이상을 거쳐 레거시 서명 토큰 및 세션이 만료되기를 기다린 후 업그레이드하거나, 계획된 재로그인 기간을 감수하는 것입니다. 이미 v3.4.1 이상을 사용 중이고 웹 키 활성화 이후 충분한 시간이 지났다면, 권고 사항에 따라 별도의 조치는 필요하지 않습니다.

docker compose logs -f zitadel-api을 사용하여 설정 단계를 모니터링하십시오. 대규모 이벤트 저장소(eventstore)의 마이그레이션은 수 분이 소요될 수 있으며, Traefik은 상태 확인이 통과될 때까지 API로 라우팅하지 않으므로 해당 시간 동안 사이트는 중단됩니다. 이를 미리 계획하십시오.

롤백은 단순히 이전 태그로 되돌리는 것만으로는 부족합니다. 마이그레이션이 실행된 후에는 이전 바이너리가 변경된 스키마를 이해하지 못하므로, 롤백하려면 덤프를 복원해야 합니다. 인스턴스에 실제 사용자가 존재하게 되면, 초기화 및 설정을 시작 단계와 분리하여 실행하는 오버레이인 docker-compose.prodlike.yml로 전환하십시오. 이렇게 하면 마이그레이션을 컨테이너 재시작의 부작용이 아닌, 사용자가 직접 트리거하고 모니터링할 수 있는 작업으로 관리할 수 있습니다.

새로운 ID 공급자를 가리키는 방법

콘솔에서 프로젝트를 생성한 다음 그 안에 애플리케이션을 만듭니다. 최신 환경이라면 OIDC를 선택하십시오. 그러면 Zitadel이 https://auth.example.com/.well-known/openid-configuration에서 클라이언트 ID, 클라이언트 시크릿, 그리고 디스커버리 문서를 제공합니다. 싱글 사인온(SSO)을 지원하는 대부분의 자체 호스팅 소프트웨어는 바로 이 정보들을 요구합니다.

많은 소프트웨어가 이를 지원하지 않거나, 유료 티어에서만 지원합니다. 전자의 경우 애플리케이션 앞단의 oauth2-proxy를 사용하면 모든 HTTP 서비스를 Zitadel이 보호할 수 있는 상태로 전환할 수 있습니다. 후자의 경우, 아직 비용을 지불하지 않은 기능을 중심으로 마이그레이션을 계획하기 전에 자체 호스팅 앱의 SSO 비용에 관한 글을 읽어보는 것이 좋습니다.

FAQ

자체 호스팅 Zitadel은 어느 정도의 RAM과 CPU가 필요한가요?

Zitadel 프로덕션 가이드에 따르면 Zitadel 자체는 약 0.5 GB의 RAM이 필요하며 1개 미만의 CPU 코어에서도 실행할 수 있습니다. 다만 비밀번호 해싱을 위해 4개의 코어를 확보할 것을 권장합니다. PostgreSQL은 별도로 산정해야 하며, 초당 100건의 요청당 약 1개의 코어와 코어당 4 GB의 RAM이 필요합니다. 가이드에 명시된 더 큰 수치는 3개 노드로 구성된 고가용성 클러스터의 노드당 사양입니다. 즉, 노드당 4 개의 코어와 16 GB의 RAM이 필요하며, 로그 수집 및 메트릭을 제외할 경우 약 4 개의 코어와 8 GB의 RAM이 필요합니다. Compose 퀵스타트에서는 최소 2 GB를 요구하는데, 이는 테스트용으로는 충분하지만 다른 서비스가 의존하는 데이터베이스를 운영하기에는 여유가 부족합니다.

Zitadel 마스터 키를 분실하면 어떻게 되나요?

마스터 키로 암호화된 모든 데이터는 암호화된 상태로 남습니다. ID 공급자 자격 증명, SMTP 비밀번호, 일회용 비밀번호(OTP) 시드는 복호화할 수 없으며, 키는 사후에 변경할 수 없습니다. 데이터베이스 덤프 파일만으로는 정상적인 인스턴스를 복구할 수 없습니다. 덤프에는 암호문만 포함되어 있고 키는 없기 때문입니다. 마스터 키는 덤프가 저장된 백업과는 별도의 장소인 비밀번호 관리자에 저장하십시오. 두 가지 모두 분실했다면 인스턴스를 처음부터 다시 구축하는 방법뿐입니다.

Zitadel 비밀번호 재설정 이메일이 도착하지 않는 이유는 무엇인가요?

SMTP 공급자가 설정되지 않았거나, 설정된 공급자가 메일을 전달하지 못하기 때문입니다. Zitadel v4.20.0은 기본적으로 레거시 알림 처리를 사용하므로 병렬 워커의 3회 재시도 및 5분 대기 설정이 무시됩니다. 인스턴스 설정에서 SMTP 공급자를 구성하고 해당 양식의 테스트 버튼을 사용하여 실제 메시지를 발송해 보십시오. 공급자를 활성화하고, VPS 공급자가 허용하는 포트에서 인증된 릴레이를 사용하십시오. 또한 발송 도메인에 대한 SPF 및 DKIM 레코드를 게시하여 메일이 스팸으로 필터링되지 않도록 하십시오.

설치 후 Zitadel 외부 도메인을 변경할 수 있나요?

네, 가능합니다. 하지만 .env만 수정해서는 안 됩니다. ZITADEL_EXTERNALDOMAIN, ZITADEL_EXTERNALPORT, ZITADEL_EXTERNALSECURE을 변경한 다음 Zitadel이 설정 단계를 다시 실행하여 변경 사항을 반영하도록 해야 합니다. 이미 등록된 애플리케이션은 이전 리다이렉트 URI를 그대로 유지하므로 수동으로 업데이트해야 합니다. 또한 Host 헤더가 Zitadel이 인식하는 도메인과 일치하지 않는 모든 요청은 Instance not found 응답을 받게 됩니다. 처음 시작하기 전에 최종 도메인 이름을 선택하면 이러한 번거로움을 피할 수 있습니다.

이 글이 도움이 되었나요?