Docker ile VPS üzerinde Zitadel self-host kurulumu
Zitadel yaklaşık 512 MB RAM kullanır. Tek VPS'te PostgreSQL, masterkey, TLS, SMTP ve yedeklemeyi Docker ile kurun; yükseltmenin veritabanına etkisini öğrenin.
VPS üzerinde Zitadel'i self-host etmek için gerekenler
Zitadel'i bir VPS üzerinde self-host etmek için bir Docker host'u, bu host'a yönlenen herkese açık bir DNS adı, PostgreSQL ve her ikisi için yeterli CPU ile RAM gerekir. Zitadel'in production kılavuzunda, uygulamanın kendisi için yaklaşık 512 MB RAM ve 1 CPU çekirdeğinden az kaynak belirtilir. Kaynak kullanımı esas olarak veritabanı ve parola hash işlemleri nedeniyle artar. Zitadel bir identity provider'dır. OIDC (OpenID Connect) ve SAML (security assertion markup language) üzerinden token üretir. Böylece diğer servislerin kendi kullanıcı listelerini tutması gerekmez. Kurulum bir curl ve bir docker compose up işleminden oluşur. Sistemin kararlı çalışıp çalışmayacağını belirleyen unsurlar masterkey, veritabanı kullanıcısı, SMTP (simple mail transfer protocol), yedek ve ilk yükseltmedir.
Aşağıdaki işlemlerin tamamında Ubuntu 24.04, Compose plugin sürümü 2.24.4 veya daha yeni olan Docker Engine 24 ya da daha yeni bir sürüm ve auth.example.com gibi sunucuya zaten çözümlenen bir ad varsayılır. TLS overlay'leri, bu Compose sürümünü gerektiren !override kullanır.
Zitadel ne kadar VPS kaynağına ihtiyaç duyar?
Zitadel dokümantasyonundaki Compose hızlı başlangıç kılavuzu 2 GB RAM talep eder. Bu değer yalnızca hızlı başlangıç içindir. Zitadel üretim ortamı kılavuzu farklı rakamlar sunar.
Bu grafiğin arkasındaki veriler
[
{
"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
}
]Bunlar, çalışan bir sunucudan alınan ölçümler değil, yayınlanmış önerilerdir. Bunları problemin genel çerçevesi olarak değerlendirin. Zitadel sürecinin kendisi küçüktür: kılavuz bunu yaklaşık 0.5 GB RAM olarak belirtir ve bir CPU çekirdeğinden daha azıyla çalışabileceğini ifade eder. Çekirdekler, kasıtlı olarak yavaş tutulan parola hashleme işlemleri içindir; bu nedenle oturum açma işlemleri bir CPU artışına neden olur ve kılavuz bu işlem için 4 CPU çekirdeğinin hazır bulundurulmasını önerir. PostgreSQL maliyetin diğer yarısını oluşturur: aynı kılavuz, saniyede 100 istek için yaklaşık bir çekirdek ve çekirdek başına 4 GB RAM bütçesi ayırır.
Daha büyük olan iki satır, tek sunuculuk rakamlar değildir. Minimum yüksek erişilebilirlik kurulumu için kılavuz, her biri 4 çekirdek ve 16 GB RAM'e sahip üç düğümlü bir küme önerir. Günlük toplama ve metrikleri devre dışı bırakırsanız, bu değerleri düğüm başına yaklaşık 4 çekirdek ve 8 GB RAM seviyesine indirebileceğinizi belirtir. Tek bir düğüm için herhangi bir boyutlandırma belirtilmemiştir.
Sonuç olarak, 2 GB bir VPS bu yığını başlatacaktır ancak bu değer, gerçek trafik geldiğinde veritabanı için kılavuzda ayrılan bütçenin oldukça altındadır. Oturum açma, diğer tüm servislerin bağımlı olduğu servistir. Bu servis kapalı olduğunda, ona güvenen hiçbir sistem kullanıcı girişi kabul etmez. Kılavuzun veritabanı ve hashleme bütçesinin, kimlik doğrulama için harcamak istediğinizden fazla olduğuna karar vermek makul bir yaklaşımdır ve bu kararı bir taşıma işleminden sonra değil, şimdi vermek çok daha ekonomiktir. Keycloak, Authentik ve Zitadel karşılaştırması, her birinin bellek ve operasyonel iş yükü açısından maliyetini ele alır; kendi kendine barındırılan bir Authentik sunucusu ise daha küçük sunucular için genellikle tercih edilen çözümdür.
Stack'i alın ve bir sürüme sabitleyin
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 .envBu dosya, gerçekten çalıştıracağınız dört servisi tanımlar. Traefik reverse proxy olarak görev yapar: path'e göre yönlendirme yapar ve aşağıda kullanılan overlay ile TLS (transport layer security) termination işlemini gerçekleştirir. zitadel-api, 8080 portunda çalışan Go binary'sidir. zitadel-login, /ui/v2/login adresinde sunulan login arayüzüdür. postgres her şeyi barındırır. Redis cache ve OpenTelemetry collector aynı dosyada Compose profillerinin arkasında bulunur ve siz etkinleştirene kadar çalışmaz.
Henüz docker compose up komutunu çalıştırmayın. İlk başlatma instance'ı oluşturur. Aşağıdaki ayarların bazıları sonradan ek işlem yapılmadan değiştirilemez.
Kopyaladığınız .env dosyası, kendi image tag'lerini sabitler:
ZITADEL_VERSION=v4.16.0
TRAEFIK_IMAGE=traefik:v3.7.7
POSTGRES_IMAGE=postgres:17.10-alpineGüncel v4 sürümü v4.20.3 olup 13 November 2026 tarihinde yayımlanmıştır. Bu sürüm, gönderilen dosyada sabitlenen sürümden dört minor sürüm ileridedir. v4.20.0 öncesindeki v4.19.5 sürümü, 15 October 2026 tarihinde yayımlanmış olup Zitadel'in teknik duyurusu A-10018 kapsamındaki ilk sürümdür: v1 ve v2 API'lerindeki etkilenen liste endpoint'leri artık varsayılan ve maksimum limitleri uygular. Bu nedenle limitsiz listeleme yapan bir client artık tüm sonuçları alamaz ve sayfalama kullanmak zorunda kalır. Maksimum değerin üzerinde sonuç isteyen bir istek reddedilir. v4.20.0 dahil olmak üzere sonraki tüm sürümler bu değişikliği içerir. Çalıştırmak istediğiniz sürümü ZITADEL_VERSION olarak ayarlayın ve en güncel sürümü otomatik olarak izlemek yerine v4 serisinde kalın. Bir sürümü elle seçerseniz v4.18.0 adımını atlayın: release notes, bu sürümde setup adımının başarısız olduğunu ve bunun yerine v4.19.0 kullanılması gerektiğini belirtir. Yukarıdaki curl, docker-compose.yml öğesini sabitlenmemiş main branch'inden alır. Bu nedenle her iki dosyanın kendi kopyanızı bir git repository'sine commit edin. Aksi halde gelecek ay yeni bir sunucuda aynı komut farklı bir dosya getirir ve neyin değiştiğini anlayamazsınız.
.env içindeki LOGIN_SESSION_COOKIE_SECRET değerini openssl rand -base64 32 ile üretilmiş rastgele bir değerle değiştirin. Login UI, session cookie'lerini imzalamak için bunu kullanır. v4.19.5 release notes da örnek değerin korunmaması gerektiği konusunda açıkça uyarır.
Postgres'e özel bir kullanıcı ve gerçek bir parola atayın
Dağıtılan .env, Zitadel'i PostgreSQL'e süper kullanıcı olarak ve postgres parolasıyla bağlar:
POSTGRES_ADMIN_USER=postgres
POSTGRES_ADMIN_PASSWORD=postgres
ZITADEL_DATABASE_POSTGRES_DSN=postgresql://postgres:postgres@postgres:5432/zitadel?sslmode=disableBuradaki sıkılaştırma adımında bir tuzak bulunmaktadır. Zitadel belgeleri POSTGRES_ZITADEL_PASSWORD değerini .env dosyasına eklemenizi söyler, ancak temel docker-compose.yml bu değişkeni hiçbir zaman okumaz; bu nedenle ayarı değiştirmek hiçbir şeyi etkilemez. POSTGRES_ADMIN_PASSWORD değerini tek başına değiştirmek ise bağlantıyı koparır, çünkü parola DSN (veri kaynağı adı) dizisinin içine doğrudan yazılmıştır. DSN, Zitadel'in nasıl bağlanacağını belirleyen satırdır.
.env.example içindeki yorumlar durumu açıkça belirtir: bir DSN yapılandırıldığında, Zitadel bu kullanıcıyı doğrudan kullanır ve sizin için yetkisiz bir kullanıcı oluşturmaz; bu nedenle rolün ilk başlatmadan önce mevcut olması gerekir. Rol için bir parola oluşturun, Postgres'i başlatmadan önce .env içinde POSTGRES_ADMIN_PASSWORD değerini rastgele bir parolaya ayarlayın, ardından Postgres'i tek başına başlatıp rolü oluşturun. Postgres imajı, yönetici parolasını yalnızca boş bir veri dizinini başlattığında uygular; .env değerini daha sonra değiştirmek, mevcut bir veritabanı parolasını güncellemez.
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;
SQLBu psql çağrıları, resmi Postgres imajının güvendiği yerel soket üzerinden container içinde çalışır, bu nedenle parola sormazlar. Önemli olan sahiplik kısmıdır. Zitadel'in başlatma aşaması kendi şemalarını (eventstore, projections, system) ve tablolarını oluşturur. Veritabanı sahipliği, role bu şemaları başlatmak için gereken CREATE yetkisini verir. PostgreSQL 15 ile public şemasındaki CREATE izinlerinde yapılan değişiklik ayrı bir konudur ve Zitadel'in şema başlatma işleminin başarısız olacağı anlamına gelmez.
Şimdi DSN'i yeni role yönlendirin ve Postgres'i başlatmadan önce ayarladığınız yönetici parolasını koruyun:
POSTGRES_ADMIN_PASSWORD=a-32-character-random-string
ZITADEL_DATABASE_POSTGRES_DSN=postgresql://zitadel:the-password-you-generated@postgres:5432/zitadel?sslmode=disablesslmode=disable, veritabanı bağlantısını özel Compose ağı üzerinde şifrelenmemiş halde bırakır; portu hiçbir zaman ana makineye açılmaz. Zitadel'in veritabanı kılavuzu, üretim ortamındaki veritabanı bağlantıları için TLS kullanılmasını önerir. İlk tam başlatmadan sonra, rolün verilerinin sahibi olduğunu doğrulayın:
docker compose exec -T postgres psql -U zitadel -d zitadel -c '\dn'Bu komut bir eventstore şeması, bir projections şeması ve bir system şeması listelemelidir. Eğer bu şemalar eksikse, başlatma aşaması o noktaya ulaşmamıştır ve API container günlüğü bunun nedenini belirtecektir.
Masterkey ve kaybedilmesinin maliyeti
Zitadel, kimlik sağlayıcı kimlik bilgileri, SMTP parolası, tek kullanımlık parola tohumları ve makine anahtarları gibi gizli verileri depolamadan önce şifreler. Masterkey, tüm bu verilerin kilidini açar. Tam olarak 32 bayt uzunluğundadır ve belgeler sonuç konusunda oldukça nettir: şifrelenmiş verilere erişimi kaybetmeden bu anahtarı değiştirmek mümkün değildir.
Bir anahtar oluşturun ve .env içindeki yer tutucu satırı bununla değiştirin:
tr -dc A-Za-z0-9 </dev/urandom | head -c 32; echoZITADEL_MASTERKEY=MasterkeyNeedsToHave32Characters satırına ikinci bir satır eklemek yerine mevcut satırı düzenleyin. Compose, tekrarlanan bir anahtarın son tanımını dikkate alır; bu nedenle ekleme yapmak teknik olarak çalışsa da, iki masterkey satırı içeren bir dosya, dosyayı daha sonra okuyacak kişi için bir tuzaktır.
Şimdi bu anahtarın nerede durduğunu düşünün. Compose dosyası, API container'ını şu şekilde başlatır:
command: start-from-init --masterkey "${ZITADEL_MASTERKEY}"Bu nedenle masterkey, container komut satırında yer alır ve docker inspect, Docker socket'ine erişebilen herkese bu değeri gösterir. Tek yöneticili bir VPS üzerinde bu kabul edilebilir bir durumdur ve .env üzerindeki mod, anahtarı diskte koruyan şeydir. Eğer bu durum kabul edilemezse, anahtarı bir dosya olarak mount edin ve değeri süreç argümanlarından uzak tutan --masterkeyFile /run/secrets/zitadel-masterkey seçeneğini kullanın.
İlk başlatmadan önce masterkey'i parola yöneticinize kopyalayın. Bu anahtar veritabanı dökümünde yer almaz; dolayısıyla farklı bir masterkey ile geri yüklenen bir döküm, kendi gizli verilerini okuyamayan bir örnek oluşturur. Anahtarı, dökümü içeren arşivden farklı bir yerde saklayın; böylece çalınan bir yedekleme hem şifrelenmiş verileri hem de o verilerin anahtarını aynı anda içermemiş olur.
İlk başlatmadan önce harici alan adını ayarlayın
ZITADEL_DOMAIN, .env içerisinde ZITADEL_EXTERNALDOMAIN değerini besler ve bu, kullanıcılarınızın tarayıcıya yazdığı isimdir. Zitadel; OIDC sağlayıcısını, giriş arayüzü temel URI adresini, SAML uç noktalarını ve ilk yöneticinin giriş adını bu değerden türetir; dolayısıyla bu sadece görsel bir ayar değildir.
ZITADEL_DOMAIN=auth.example.com
ZITADEL_EXTERNALPORT=443
ZITADEL_EXTERNALSECURE=trueZitadel, hangi örneğe (instance) erişmeye çalıştığınızı Host başlığından çözer. Eğer bu başlık, sistemin bildiği bir alan adıyla eşleşmezse, her istek aynı yanıtı alır:
ID=QUERY-1kIjX Message=Instance not foundBu hatayı gördüğünüzde iki durumu kontrol edin. Ya ZITADEL_DOMAIN tarayıcınızda girdiğiniz isim değildir ya da ön taraftaki bir proxy, Host değerini upstream adresine göre yeniden yazıyordur. Sunucunun ismini girmek yerine IP adresine gitmek de aynı sonucu doğurur.
Bu değerleri daha sonra değiştirebilirsiniz. Zitadel'in değişikliği algılaması için kurulum aşamasını yeniden çalıştırması gerekir ve halihazırda kaydettiğiniz her uygulama eski yönlendirme URI adreslerini korumaya devam eder. Nihai ismi şimdi belirlemek, daha sonra taşımaktan çok daha zahmetsizdir.
Let's Encrypt katmanı ile TLS sonlandırma
Halka açık bir alan adı için Zitadel'in Let's Encrypt katmanını ekleyin. Bu katman, Traefik'i ACME (otomatik sertifika yönetimi ortamı) HTTP sınamasına geçirir ve yayınlanan portları 80 ve 443 ile değiştirir; bu nedenle sunucudaki başka hiçbir servis bu portları kullanamaz.
curl -fsSLO https://raw.githubusercontent.com/zitadel/zitadel/main/deploy/compose/docker-compose.mode-letsencrypt.yml
echo 'LETSENCRYPT_EMAIL=ops@example.com' >> .envBu katman ayrıca API container'ı üzerinde ZITADEL_EXTERNALPORT: 443 ve ZITADEL_EXTERNALSECURE: true ayarlarını yapılandırır; bu sayede genel URL ile Zitadel'in kendi oluşturduğu URL'ler birbiriyle uyumlu hale gelir. HTTP sınaması bu kayıt olmadan başarısız olacağından, başlatma işleminden önce A kaydının çözümlendiğinden emin olun.
TLS sonlandırmasını halihazırda nginx veya bir yük dengeleyici üzerinde yapıyorsanız, bunun yerine docker-compose.mode-external-tls.yml kullanın ve TRAEFIK_TRUSTED_IPS değerini proxy'nizin istek gönderdiği aralıklarla ayarlayın. Traefik, yalnızca bu listedeki adreslerden gelen X-Forwarded-* başlıklarını dikkate alır. Katman, Zitadel'in harici URL'sini ve giriş URL'lerini açıkça HTTPS olarak ayarlar.
Bir upstream proxy'nin Zitadel konusunda katı olduğu iki görevi vardır. API gRPC tabanlı olduğu için backend ile HTTP/2 üzerinden iletişim kurmalıdır. Ayrıca Host başlığını, X-Forwarded-Proto: https ile birlikte değiştirmeden iletmelidir. Bu Compose yığını ile nginx yapılandırması şu şekildedir:
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;
}
}Upstream yer tutucularını nginx'in erişebileceği adreslerle değiştirin. Zitadel'i 443 dışındaki bir porttan sunuyorsanız, portun başlık ile birlikte iletilmesi için grpc_set_header Host $host:$server_port; kullanın. Yapılandırmanın geri kalanı standart bir sanal ana bilgisayar ayarıdır ve satır satır nginx reverse proxy yapılandırması rehberi, Zitadel'e özel olmayan kısımları kapsamaktadır.
İlk yönetici ve parola değişikliğini zorunlu kılma
İlk başlatma bir instance, bir organisation ve bir insan admin hesabı oluşturur. Giriş adı zitadel-admin@, zitadel. ve harici alan adınızın birleşiminden oluşur. ZITADEL_DOMAIN=auth.example.com kullanıldığında ad şu olur:
zitadel-admin@zitadel.auth.example.comParola, kendi parolanızı belirlemediyseniz Password1! olur. Zitadel upstream varsayılanında ilk girişte parola değişikliğini zorunlu kılar. Ancak dağıtımla gelen compose dosyası bu varsayılanı geçersiz kılar:
ZITADEL_FIRSTINSTANCE_ORG_HUMAN_PASSWORDCHANGEREQUIRED: falseBu satır .env dosyasından okunmaz; doğrudan docker-compose.yml içinde sabit olarak tanımlanmıştır. Bu nedenle kendi değerlerinizi size ait küçük bir overlay dosyasına koyun. Dosyayı docker-compose.local.yml olarak adlandırın:
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, docker-compose.override.yml dosyasını yalnızca -f flag'i olmadan çalıştırıldığında kendiliğinden yükler. Zitadel kılavuzundaki her komut -f gönderdiği için bu davranış devre dışı kalır. Giderek uzayan flag listesini her seferinde tekrarlamak yerine dosya listesini .env içinde sabitleyin:
COMPOSE_FILE=docker-compose.yml:docker-compose.mode-letsencrypt.yml:docker-compose.local.ymlŞimdi başlatın:
docker compose pull
docker compose up -d --wait--wait, healthcheck kontrolleri başarılı olana kadar komutu bekletir. API container'ı bu duruma hiç ulaşamazsa Compose dependency failed to start: container zitadel-zitadel-api-1 is unhealthy ile durur. Nedeni docker compose logs zitadel-api içinde bulunur. Container, project adını temel alan bir adla oluşturulur. Dağıtımla gelen compose dosyası bunu üst düzey name: zitadel ile kendisi belirlediği için dizin adı kullanılmaz. İlk başlatmada neden genellikle masterkey uzunluğu veya veritabanı DSN değeridir.
https://auth.example.com/ui/console adresinden giriş yapın, parolayı değiştirin ve başka bir şey oluşturmadan önce bu hesap için ikinci faktörü etkinleştirin. Her ZITADEL_FIRSTINSTANCE_* değeri yalnızca ilk instance oluşturulurken geçerlidir. Instance oluşturulduktan sonra bu değerleri düzenlemek hiçbir şeyi değiştirmez.
Parola sıfırlama işlemi neden SMTP çalışana kadar sonuç vermez
E-posta gönderemeyen bir kimlik sağlayıcı, haftalarca fark edilmeyecek şekilde bozuk kalır. Zitadel; kullanıcı davetleri, adres doğrulama, parola sıfırlama bağlantıları, tek kullanımlık kodlar ve alan adı sahiplik bildirimleri için e-posta gönderir. Bir SMTP sağlayıcısı yapılandırılmadığında, Konsol işlemi tamamlanmış gibi raporlar ancak mesaj, gönderilecek bir yer bulunamadığı için bildirim işleme kuyruğuna takılır. v4.20.0 sürümünde bildirimler varsayılan olarak eski (legacy) modu kullanır (LegacyEnabled: true); bu mod, paralel işleyicinin MaxAttempts: 3 ve MaxTtl: 5m ayarlarını yok sayar. Bu değerler, varsayılan bildirim yeniden deneme davranışını tanımlamaz. Bağlantıyı bekleyen kişiye herhangi bir bildirim gitmez.
Yapılandırmayı Konsol üzerinde, örnek (instance) ayarları altındaki https://auth.example.com/ui/console/settings kısmından yapın. SMTP sağlayıcı formu; gönderen e-posta adresi, gönderen adı, ana makine (host) ve port, kullanıcı adı, SMTP parolası ve TLS anahtarı ister. Kaydetmeden önce formdaki test butonunu kullanın; bu buton gerçek bir mesaj gönderir, böylece mesajın ulaşıp ulaşmadığını anında görürsünüz. Zitadel'in e-posta göndermesi için sağlayıcıyı etkinleştirin.
Bununla eşleşen bir ortam değişkeni seti (ZITADEL_DEFAULTINSTANCE_SMTPCONFIGURATION_SMTP_HOST ve türevleri) mevcuttur. Bunlar, bir örnek ilk kez oluşturulduğunda geçerli olur. Hali hazırda çalışan bir yığında (stack) bu değişkenlerin etkisi yoktur; bu nedenle mevcut bir örnek için en doğru yer Konsol'dur.
Bir VPS üzerinden gönderim yaparken dikkat edilmesi gereken iki husus vardır, çünkü sorun genellikle burada yaşanır. Bir aktarıcı (relay) seçmeden önce sağlayıcınızın giden SMTP politikasını kontrol edin: DigitalOcean, Droplet'lerde varsayılan olarak 25, 465 ve 587 numaralı portları engeller; bu nedenle 587 numaralı port evrensel bir çözüm değildir. Sağlayıcınızın izin verdiği bir port üzerinde kimlik doğrulamalı bir aktarıcı kullanın. Ayrıca gönderen alan adı için SPF (sender policy framework) ve DKIM (domainkeys identified mail) kayıtlarını yayınlayın; aksi takdirde sıfırlama bağlantısı spam kutusuna düşer ve bu durum kullanıcıya e-postanın hiç gönderilmediği izlenimini verir.
v4.20.0 sürümünde, giden SMTP TLS bağlantıları, güvenliği ihlal edilmiş eMudhra ara CA'ları üzerinden gelen sertifika zincirlerini reddeder. Etkilenen bir aktarıcının sertifikasının değiştirilmesi gerekir.
Kimseyi davet etmeden önce sistemi test edin. Geçici bir kullanıcı oluşturun, parola sıfırlama isteğinde bulunun ve mesajın ulaşıp ulaşmadığını izleyin. Eğer ulaşmazsa, docker compose logs -f zitadel-api SMTP hatasını belirtir. SMTP parolası veritabanında şifrelenmiş olarak saklanır; bu da ana anahtarın (masterkey) sizin için koruduğu bir diğer veridir.
Postgres ve masterkey verilerini ayrı ayrı yedekleyin
Zitadel'in bildiği her şey PostgreSQL içinde yer alır. Verilerin şifresini çözen öğe ise masterkey bilgisidir. Bunları iki farklı yere yedekleyin.
Önce dump işlemini gerçekleştirin:
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, dışa aktarım sırasında sıkıştırma yapan ve pg_restore aracının seçici olarak okuyabildiği özel formattır. exec -T, terminal bağlantısını keser; bu, cron üzerinden terminal olmadan çalıştırılan işlemler için önemlidir.
Ardından, şifreleme ve tekilleştirme yapan restic ile bu dizini sunucu dışına gönderin:
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 --prunerestic init komutu yalnızca ilk gün, bir kez çalıştırılır. Dump işlemini ve son iki komutu /usr/local/bin/zitadel-backup.sh dosyasına ekleyin ve her gece çalışacak şekilde ayarlayın:
0 3 * * * /usr/local/bin/zitadel-backup.sh.env dizinini ve kullandığınız tüm compose dosyalarını git üzerinde yedekleyin. Masterkey, tüm bu kuralların istisnasıdır. Bu anahtar, parola yöneticinizde ve restic deposundan farklı ikinci bir konumda bulunmalıdır; çünkü veritabanını ve onun şifre çözme anahtarını aynı arşivde tutmak, şifreli bir sistemin yedekleme amacını ortadan kaldırır.
Geri yüklemesini yapmadığınız bir yedekleme, sadece bir tahmindir. Aynı sunucuda geçici bir veritabanına geri yükleme yapın ve kontrol edin:
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_testeventstore şemasındaki tabloların listelenmesi, dump dosyasının geçerli olduğunu gösterir. Şemanın bulunamadığına dair bir hata alırsanız yedekleme geçersizdir; bunu, herhangi bir kayıp yaşamadığınız bir günde fark etmiş oldunuz. Compose yığınlarını yedekleme ve yükseltme için genel yöntem, burada neredeyse hiç değişiklik olmadan uygulanabilir; masterkey bilgisini aynı arşivin dışında tutmak, Zitadel'e özgü tek kısımdır.
Instance'ı kaybetmeden Zitadel'i yükseltin
Yükseltme, .env içindeki sürümün değiştirilmesinin ardından iki komutun çalıştırılmasından oluşur:
docker compose pull
docker compose up -d --waitBu komutu, kullanıcıların login olduğu bir sistemde çalıştırmadan önce ikinci komutun ne yaptığını anlayın. Container'ın komutu start-from-init şeklindedir. Bu komut, servis sunmaya başlamadan önce init ve setup aşamalarını çalıştırır. Setup aşaması veritabanı migration'larını gerçekleştirir. Bu nedenle sürüm yükseltildiğinde schema migration'ları container başlarken canlı veritabanına, etkileşim olmadan uygulanır. Bu sırada --wait healthcheck'i bekler. Restore testinin isteğe bağlı olmamasının temel nedeni budur.
Yükseltmeden hemen önce güncel bir dump alın. Önceki gece alınan dump aynı şey değildir.
v4.20.3 için devam eden external identity provider login işlemleri yeniden başlatılmalıdır. Kullanılmamış Login V1 authorization code'ları bir kez reddedilir. Özel login UI'ların OIDC veya SAML isteklerini tamamlayabilmesi için session.link izni gerekir. Yükseltmeden önce service user'a IAM_LOGIN_CLIENT rolünü verin. Gönderilen Login V2 service user'ında bu rol zaten bulunur. Session API parola kontrolleri artık kullanıcının organization login policy'sini uygular. Bu nedenle username/password login'i devre dışı bırakan organization'lar kullanıcıları identity provider'larına yönlendirmelidir.
Major version atlamayın. v3'ten v4'e geçmeden önce en az v3.4.1 sürümüne yükselin. v4, OIDC web key'lerini zorunlu kılar ve legacy signing path'i kaldırır. Bu nedenle v3 instance'ınız web key'lerini hiç etkinleştirmediyse eski legacy key'lerle imzalanan token'lar yükseltmeden sonra doğrulanamaz. Zitadel'in teknik duyurusu A-10017, mevcut JWT access token'larının ve ID token'larının hemen geçersiz hale gelebileceğini ve kullanıcıların yeniden login olması gerekebileceğini belirtir. Çözüm olarak v3.4.1 veya daha yeni bir sürüm üzerinden geçiş yapılması ve yükseltmeden önce legacy imzalı token'ların ve session'ların süresinin dolmasının beklenmesi önerilir. Alternatif olarak planlı bir yeniden login penceresi kabul edilebilir. Zaten v3.4.1 veya daha yeni bir sürüm çalışıyorsa ve web key'leri etkinleştirildikten sonra yeterli süre beklendiyse advisory'ye göre işlem gerekmez.
Setup aşamasını docker compose logs -f zitadel-api ile izleyin. Büyük bir eventstore üzerindeki migration'lar birkaç dakika sürebilir. Traefik, healthcheck başarılı olana kadar API'ye yönlendirme yapmaz. Bu nedenle site bu süre boyunca erişilemez olur. Bu durumu sonradan fark etmek yerine planlayın.
Rollback yalnızca eski tag'i geri koymaktan ibaret değildir. Migration'lar çalıştıktan sonra eski binary, karşılaştığı schema'yı anlayamaz. Bu nedenle rollback işlemi dump'ı restore etmeyi gerektirir. Instance gerçek kullanıcıları barındırmaya başladıktan sonra init ve setup işlemlerini start işleminden ayrı adımlar olarak çalıştıran docker-compose.prodlike.yml overlay'ine geçin. Böylece migration, container restart işleminin yan etkisi olarak değil, sizin başlattığınız ve izlediğiniz bir işlem olur.
Yeni kimlik sağlayıcınıza neyi işaret etmelisiniz
Console üzerinde bir proje oluşturun ve ardından içinde bir uygulama tanımlayın. Modern tüm yapılar için OIDC seçeneğini tercih edin; Zitadel size bir client ID, bir client secret ve https://auth.example.com/.well-known/openid-configuration adresinde bir discovery document sunacaktır. Single sign-on destekleyen çoğu self-hosted yazılım tam olarak bu bilgilere ihtiyaç duyar.
Pek çok yazılım bu desteği sunmaz veya yalnızca ücretli sürümlerinde destekler. İlk durum için, uygulamanın önünde oauth2-proxy kullanımı, herhangi bir HTTP servisini Zitadel tarafından korunabilir hale getirir. İkinci durum için, self-hosted uygulamalarda SSO maliyeti, henüz ödeme yapmadığınız bir özellik üzerine geçiş planlamadan önce okunmalıdır.
FAQ
Kendi kendine barındırılan (self-hosted) Zitadel ne kadar RAM ve CPU gerektirir?
Zitadel üretim kılavuzuna göre Zitadel'in kendisi yaklaşık 0.5 GB RAM gerektirir ve bir CPU çekirdeğinden daha azıyla çalışabilir; ancak parola karma işlemleri için 4 çekirdek ayrılması önerilir. PostgreSQL için kaynak planlaması ayrı yapılır; saniyede 100 istek için yaklaşık bir çekirdek ve çekirdek başına 4 GB RAM öngörülür. Kılavuzdaki daha yüksek değerler, üç düğümlü yüksek erişilebilirlik kümesindeki her bir düğüm içindir: düğüm başına 4 çekirdek ve 16 GB; günlük toplama ve metrikler hariç tutulduğunda ise yaklaşık 4 çekirdek ve 8 GB gereklidir. Compose hızlı başlangıç kurulumu en az 2 GB RAM ister; bu miktar deneme yapmak için yeterlidir ancak sistemin ihtiyaç duyduğu diğer servislerin veritabanı için çok az alan bırakır.
Zitadel ana anahtarını (masterkey) kaybedersem ne olur?
Bu anahtarla şifrelenmiş her şey şifreli kalır. Kimlik sağlayıcı kimlik bilgileri, SMTP parolası ve tek kullanımlık parola (OTP) tohumları şifresi çözülemez hale gelir ve anahtar sonradan değiştirilemez. Veritabanı yedeği tek başına çalışan bir örneği geri yükleyemez, çünkü yedek şifreli metinleri içerir ve anahtarı barındırmaz. Ana anahtarı, yedeği içeren depolama alanından ayrı bir yerde, bir parola yöneticisinde saklayın. Her ikisi de kaybolursa, tek çözüm örneği sıfırdan yeniden oluşturmaktır.
Zitadel parola sıfırlama e-postaları neden ulaşmıyor?
Çünkü bir SMTP sağlayıcısı yapılandırılmamıştır veya yapılandırılan sağlayıcı teslimat yapamıyordur. Zitadel v4.20.0 varsayılan olarak eski bildirim işleme yöntemini kullanır, bu nedenle paralel işleyicinin üç deneme ve beş dakikalık ayarları dikkate alınmaz. SMTP sağlayıcısını örnek ayarları altından yapılandırın ve formdaki, gerçek bir ileti gönderen test düğmesini kullanın. Sağlayıcıyı etkinleştirin, VPS sağlayıcınızın izin verdiği bir port üzerinde kimlik doğrulamalı bir aktarıcı (relay) kullanın ve gönderen alan adı için SPF ve DKIM kayıtlarını yayınlayın; böylece postalar spam olarak filtrelenmez.
Kurulumdan sonra Zitadel dış alan adını değiştirebilir miyim?
Evet, ancak yalnızca .env dosyasını düzenleyerek değil. ZITADEL_EXTERNALDOMAIN, ZITADEL_EXTERNALPORT ve ZITADEL_EXTERNALSECURE değerlerini değiştirin, ardından Zitadel'in kurulum aşamasını yeniden çalıştırmasına izin vererek değişikliği algılamasını sağlayın. Daha önce kaydettiğiniz uygulamalar eski yönlendirme URI'lerini korur ve manuel olarak güncellenmeleri gerekir; ayrıca Host başlığı Zitadel'in bildiği bir alan adıyla eşleşmeyen her istek Instance not found yanıtını alır. İlk başlatmadan önce nihai alan adını seçmek tüm bu süreçten kaçınmanızı sağlar.