Docker के साथ VPS पर Zitadel self-host कैसे करें
Zitadel को VPS पर चलाने के लिए लगभग 512 MB RAM चाहिए। Postgres, masterkey, TLS, SMTP और backups सेट करें, फिर upgrade के database प्रभाव को समझें।
VPS पर Zitadel को self-host करने के लिए आवश्यक चीज़ें
VPS पर Zitadel को self-host करने के लिए आपको Docker host, उस host की ओर संकेत करने वाला public DNS name, PostgreSQL और दोनों के लिए पर्याप्त CPU और RAM चाहिए। Zitadel की production guide के अनुसार application को लगभग 512 MB RAM और 1 CPU core से कम चाहिए। अधिक संसाधन database और password hashing लेते हैं। Zitadel एक identity provider है। यह OIDC (OpenID Connect) और SAML (security assertion markup language) के माध्यम से tokens जारी करता है, ताकि आपकी अन्य services को अपनी user lists बनाए रखने की जरूरत न पड़े। Installation एक curl और एक docker compose up है। इसके सही तरीके से चलते रहने का निर्णय masterkey, database user, SMTP (simple mail transfer protocol), backup और पहले upgrade से होता है।
नीचे दिए गए सभी चरण Ubuntu 24.04, Compose plugin version 2.24.4 या नए version वाले Docker Engine 24 या नए version और पहले से server पर resolve होने वाले auth.example.com जैसे name को मानकर चलते हैं। TLS overlays में !override का उपयोग होता है, जिसके लिए यह Compose version आवश्यक है।
Zitadel को कितने VPS की आवश्यकता है?
Zitadel के docs में दिया गया Compose quickstart 2 GB RAM की मांग करता है। वह संख्या केवल quickstart के लिए है। Zitadel की production guide में अलग आंकड़े दिए गए हैं।
इस चार्ट के पीछे का डेटा
[
{
"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 process स्वयं छोटी है: guide के अनुसार यह लगभग 0.5 GB RAM लेती है और एक CPU core से कम पर चल सकती है। Cores की आवश्यकता password hashing के लिए होती है, जो जानबूझकर धीमी रखी गई है, इसलिए logins का एक साथ आना CPU spike का कारण बनता है। guide इसके लिए 4 CPU cores उपलब्ध रखने की सलाह देती है। PostgreSQL इस खर्च का दूसरा हिस्सा है: वही guide प्रति 100 requests प्रति सेकंड के लिए लगभग एक core और प्रति core 4 GB RAM का बजट बताती है।
दो बड़ी पंक्तियाँ single-box के आंकड़े नहीं हैं। न्यूनतम high-availability setup के लिए guide तीन nodes के cluster की सिफारिश करती है, जिसमें प्रत्येक में 4 cores और 16 GB RAM हो। guide यह भी कहती है कि यदि आप log collection और metrics को हटा दें, तो इसे घटाकर प्रति node लगभग 4 cores और 8 GB किया जा सकता है। यह single node के लिए कोई sizing नहीं बताती है।
अतः, एक 2 GB का VPS इस stack को start तो कर देगा, लेकिन यह उस बजट से काफी कम है जो guide केवल database के लिए निर्धारित करती है जब वास्तविक traffic आता है। Login वह service है जिस पर अन्य सभी services निर्भर करती हैं। जब यह down होती है, तो इस पर भरोसा करने वाली कोई भी service किसी को access नहीं देती। यह निर्णय लेना कि guide का database और hashing बजट authentication पर खर्च करने के लिए बहुत अधिक है, एक उचित निर्णय है, और migration के बाद की तुलना में अभी यह निर्णय लेना काफी सस्ता है। Keycloak, Authentik और Zitadel की तुलना में बताया गया है कि प्रत्येक की memory और operational कार्य के संदर्भ में क्या लागत है, और एक self-hosted Authentik server छोटे सर्वर के लिए सामान्य समाधान है।
Stack प्राप्त करें और version pin करें
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यह file वे चार services define करती है जिन्हें आप वास्तव में चलाएँगे। Traefik reverse proxy है: यह path के आधार पर routing करता है और नीचे दिए गए overlay के साथ TLS (transport layer security) termination करता है। zitadel-api port 8080 पर चलने वाला Go binary है। zitadel-login /ui/v2/login पर उपलब्ध login interface है। postgres सब कुछ संभालता है। Redis cache और OpenTelemetry collector इसी file में Compose profiles के पीछे मौजूद हैं और आपके कहने तक बंद रहते हैं।
अभी docker compose up न चलाएँ। पहली बार start करने पर instance बनता है और नीचे दी गई कई settings को बाद में अतिरिक्त काम के बिना बदला नहीं जा सकता।
आपने जो .env copy किया है, वह अपने image tags को pin करता है:
ZITADEL_VERSION=v4.16.0
TRAEFIK_IMAGE=traefik:v3.7.7
POSTGRES_IMAGE=postgres:17.10-alpineवर्तमान v4 release v4.20.3 है, जो 13 November 2026 को जारी हुआ और shipped file में मौजूद pin से चार minor versions आगे है। v4.20.0 से पहले का release v4.19.5, जो 15 October 2026 को जारी हुआ, Zitadel की technical advisory A-10018 में शामिल पहला release है: v1 और v2 APIs में प्रभावित list endpoints अब default और maximum limits लागू करते हैं। इसलिए बिना limit के list करने वाले client को अब हर result नहीं मिलता और उसे pagination करनी पड़ती है। Maximum से अधिक माँगने वाली request अस्वीकार कर दी जाती है। इसके बाद के सभी releases, जिनमें v4.20.0 भी शामिल है, यह बदलाव रखते हैं। ZITADEL_VERSION को उस version पर set करें जिसे आप चलाना चाहते हैं और v4 line पर बने रहें; नवीनतम version को स्वतः track न करें। यदि आप version manually चुनते हैं तो v4.18.0 को छोड़ दें: उसके release notes के अनुसार उस version में setup step fail होता है और v4.19.0 का उपयोग करना चाहिए। ऊपर दिया गया curl main branch से docker-compose.yml प्राप्त करता है, जो किसी निश्चित version पर pinned नहीं है। इसलिए दोनों files की अपनी copies को git repository में commit करें। अन्यथा अगले महीने किसी नए box पर वही command अलग file दे सकती है और आपको पता नहीं चलेगा कि क्या बदला।
.env में LOGIN_SESSION_COOKIE_SECRET को openssl rand -base64 32 से generated random value से replace करें। Login UI इसका उपयोग session cookies पर हस्ताक्षर करने के लिए करता है। v4.19.5 के release notes में example value को बनाए रखने के विरुद्ध स्पष्ट चेतावनी दी गई है।
Postgres को अपना यूजर और एक वास्तविक पासवर्ड दें
शिप किया गया .env, Zitadel को PostgreSQL से superuser के रूप में जोड़ता है, जिसका पासवर्ड postgres है:
POSTGRES_ADMIN_USER=postgres
POSTGRES_ADMIN_PASSWORD=postgres
ZITADEL_DATABASE_POSTGRES_DSN=postgresql://postgres:postgres@postgres:5432/zitadel?sslmode=disableयहाँ hardening चरण में एक जाल है। Zitadel के docs आपको POSTGRES_ZITADEL_PASSWORD को .env में जोड़ने के लिए कहते हैं, लेकिन base docker-compose.yml उस variable को कभी नहीं पढ़ता है, इसलिए उसे सेट करने से कुछ नहीं बदलता। केवल POSTGRES_ADMIN_PASSWORD को बदलने से connection टूट जाता है, क्योंकि पासवर्ड DSN (data source name) स्ट्रिंग के अंदर भी literal रूप में लिखा होता है। DSN वह लाइन है जो यह तय करती है कि Zitadel कैसे connect होगा।
.env.example में टिप्पणियाँ इसे स्पष्ट रूप से बताती हैं: जब एक DSN कॉन्फ़िगर किया जाता है, तो Zitadel सीधे उस यूजर का उपयोग करता है और आपके लिए unprivileged यूजर नहीं बनाता है, इसलिए पहली बार start करने से पहले role का अस्तित्व में होना आवश्यक है। role के लिए एक पासवर्ड जनरेट करें, Postgres start करने से पहले .env में POSTGRES_ADMIN_PASSWORD को एक अलग रैंडम पासवर्ड पर सेट करें, फिर Postgres को अपने आप start करें और role बनाएँ। Postgres इमेज केवल तभी उस admin पासवर्ड को लागू करती है जब वह एक खाली डेटा डायरेक्टरी को इनिशियलाइज़ करती है; बाद में .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 इमेज भरोसा करती है, इसलिए वे पासवर्ड नहीं माँगते हैं। स्वामित्व (ownership) वह हिस्सा है जो मायने रखता है। Zitadel का init चरण अपने स्वयं के schemas (eventstore, projections, system) और टेबल बनाता है। डेटाबेस का स्वामित्व role को उन schemas को बूटस्ट्रैप करने के लिए आवश्यक CREATE विशेषाधिकार देता है। PostgreSQL 15 का public schema पर CREATE अनुमतियों में बदलाव अलग है और इसका मतलब यह नहीं है कि Zitadel का schema बूटस्ट्रैप विफल हो गया है।
अब DSN को नए role पर पॉइंट करें, और Postgres start करने से पहले सेट किए गए admin पासवर्ड को बनाए रखें:
POSTGRES_ADMIN_PASSWORD=a-32-character-random-string
ZITADEL_DATABASE_POSTGRES_DSN=postgresql://zitadel:the-password-you-generated@postgres:5432/zitadel?sslmode=disablesslmode=disable डेटाबेस कनेक्शन को प्राइवेट Compose नेटवर्क पर unencrypted छोड़ देता है; इसका पोर्ट कभी भी होस्ट पर पब्लिश नहीं होता है। Zitadel की डेटाबेस गाइड प्रोडक्शन डेटाबेस कनेक्शन के लिए TLS की सिफारिश करती है। पहली बार पूरी तरह start होने के बाद, जाँचें कि क्या role वास्तव में अपने डेटा का स्वामी है:
docker compose exec -T postgres psql -U zitadel -d zitadel -c '\dn'इससे एक eventstore schema, एक projections schema और एक system schema की सूची आनी चाहिए। यदि वे schemas गायब हैं, तो init चरण वहाँ तक कभी नहीं पहुँचा, और API कंटेनर लॉग में इसका कारण बताया जाएगा।
Masterkey और इसे खोने का परिणाम
Zitadel secrets को स्टोर करने से पहले उन्हें encrypt करता है: identity provider credentials, SMTP password, one-time-password seeds और machine keys। Masterkey इन सभी को unlock करता है। यह ठीक 32 bytes का होता है, और documentation इसके परिणाम के बारे में स्पष्ट है: इसे बदले जाने पर encrypted data का access खो जाता है।
एक key generate करें और .env में placeholder line को बदलें:
tr -dc A-Za-z0-9 </dev/urandom | head -c 32; echoZITADEL_MASTERKEY=MasterkeyNeedsToHave32Characters line को edit करें, न कि दूसरी line append करें। Compose एक ही key की अंतिम definition को मानता है, इसलिए append करना काम तो करेगा, लेकिन जिस file में दो masterkey lines होंगी, वह भविष्य में इसे पढ़ने वाले के लिए एक जाल साबित होगी।
अब सोचें कि यह key कहाँ रहती है। Compose file API container को इस तरह start करती है:
command: start-from-init --masterkey "${ZITADEL_MASTERKEY}"इसलिए masterkey container command line पर स्थित होता है, जहाँ docker inspect इसे किसी भी ऐसे व्यक्ति को दिखा सकता है जो Docker socket तक पहुँच सकता है। एक single-admin VPS पर यह एक स्वीकार्य समझौता है, और .env का mode इसे disk पर सुरक्षित रखता है। यदि यह स्वीकार्य नहीं है, तो key को file के रूप में mount करें और इसके बजाय --masterkeyFile /run/secrets/zitadel-masterkey का उपयोग करें, जो value को process arguments से बाहर रखता है।
पहली बार start करने से पहले masterkey को अपने password manager में copy करें। यह database dump में दिखाई नहीं देता है, इसलिए एक अलग masterkey के तहत restore किया गया dump एक ऐसा instance बनाता है जो अपने स्वयं के secrets को नहीं पढ़ सकता। इसे उस archive के अलावा कहीं और रखें जिसमें dump मौजूद है, ताकि एक चोरी हुए backup में encrypted data और उसे खोलने वाली key दोनों न हों।
पहली बार start करने से पहले external domain सेट करें
ZITADEL_DOMAIN, .env में ZITADEL_EXTERNALDOMAIN को फीड करता है, और यही वह नाम है जिसे आपके users टाइप करते हैं। Zitadel इसी से OIDC issuer, login interface base URI, SAML endpoints और पहले admin का login नाम निर्धारित करता है, इसलिए यह केवल दिखावटी नहीं है।
ZITADEL_DOMAIN=auth.example.com
ZITADEL_EXTERNALPORT=443
ZITADEL_EXTERNALSECURE=trueZitadel यह पहचानता है कि आप किस instance से बात कर रहे हैं, इसके लिए वह Host header का उपयोग करता है। यदि वह header किसी ज्ञात domain से मेल नहीं खाता है, तो हर request का एक ही उत्तर मिलता है:
ID=QUERY-1kIjX Message=Instance not foundजब आप यह error देखें, तो दो चीजों की जाँच करें। या तो ZITADEL_DOMAIN वह नाम नहीं है जिस पर आप browse कर रहे हैं, या सामने मौजूद कोई proxy Host को upstream address पर rewrite कर रहा है। नाम के बजाय server के IP address पर browse करने से भी यही error आता है।
आप इन values को बाद में बदल सकते हैं। बदलाव को लागू करने के लिए Zitadel को अपना setup phase फिर से चलाना पड़ता है, और आपके द्वारा पहले से register की गई हर application अपने पुराने redirect URIs को ही बनाए रखती है। अंतिम नाम अभी चुन लेना, बाद में उसे बदलने की तुलना में बहुत आसान है।
Let's Encrypt overlay के साथ TLS terminate करें
Public domain के लिए, Zitadel का Let's Encrypt overlay जोड़ें। यह Traefik को ACME (automatic certificate management environment) HTTP challenge पर स्विच कर देता है और published ports को 80 और 443 से बदल देता है, इसलिए सर्वर पर कोई अन्य सेवा इन ports का उपयोग नहीं कर सकती।
curl -fsSLO https://raw.githubusercontent.com/zitadel/zitadel/main/deploy/compose/docker-compose.mode-letsencrypt.yml
echo 'LETSENCRYPT_EMAIL=ops@example.com' >> .envयह overlay API container पर ZITADEL_EXTERNALPORT: 443 और ZITADEL_EXTERNALSECURE: true भी सेट करता है, यही कारण है कि public URL और Zitadel द्वारा स्वयं के लिए बनाए गए URL मेल खाते हैं। शुरू करने से पहले A record का resolve होना आवश्यक है, क्योंकि इसके बिना HTTP challenge विफल हो जाता है।
यदि आप पहले से ही nginx या load balancer पर TLS terminate करते हैं, तो इसके बजाय docker-compose.mode-external-tls.yml का उपयोग करें और TRAEFIK_TRUSTED_IPS को उन ranges पर सेट करें जहाँ से आपका proxy traffic भेजता है। Traefik केवल उस सूची में शामिल addresses से प्राप्त X-Forwarded-* headers का ही सम्मान करता है। यह overlay स्पष्ट रूप से Zitadel के external URL और login URLs को HTTPS पर सेट करता है।
Upstream proxy के दो कार्य हैं जिन्हें लेकर Zitadel सख्त है। इसे backend से HTTP/2 में बात करनी चाहिए, क्योंकि API gRPC है। और इसे Host को X-Forwarded-Proto: https के साथ बिना किसी बदलाव के आगे बढ़ाना चाहिए। इस Compose stack के साथ, nginx configuration का स्वरूप इस प्रकार है:
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 placeholders को उन addresses से बदलें जिन तक nginx पहुँच सकता है। यदि आप Zitadel को 443 के अलावा किसी अन्य port पर serve करते हैं, तो grpc_set_header Host $host:$server_port; का उपयोग करें ताकि port header के साथ आगे बढ़ सके। बाकी एक सामान्य virtual host है, और nginx reverse proxy config का पंक्ति-दर-पंक्ति विवरण उन हिस्सों को कवर करता है जो Zitadel-विशिष्ट नहीं हैं।
पहले admin और password change को अनिवार्य करना
पहली बार start करने पर एक instance, एक organisation और एक human admin बनता है। Login name zitadel-admin@, zitadel. और आपके external domain को जोड़कर बनता है। इसलिए ZITADEL_DOMAIN=auth.example.com के साथ यह होगा:
zitadel-admin@zitadel.auth.example.comयदि आपने अपना password set नहीं किया है, तो password Password1! है। Zitadel का upstream default पहले login पर password change को अनिवार्य करता है, लेकिन shipped compose file इस default को override करती है:
ZITADEL_FIRSTINSTANCE_ORG_HUMAN_PASSWORDCHANGEREQUIRED: falseयह line .env से read होने के बजाय docker-compose.yml में hardcoded है। इसलिए अपनी values एक छोटे 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 अपने-आप docker-compose.override.yml को तभी load करता है, जब आप इसे बिना -f flag के run करते हैं। Zitadel की guide में हर command -f pass करती है, जिससे यह सुविधा बंद हो जाती है। बार-बार बढ़ती हुई flags की list दोहराने के बजाय, file list को .env में तय करें:
COMPOSE_FILE=docker-compose.yml:docker-compose.mode-letsencrypt.yml:docker-compose.local.ymlअब इसे start करें:
docker compose pull
docker compose up -d --waitHealthchecks pass होने तक --wait command को रोके रखता है। जब API container उस स्थिति तक नहीं पहुँचता, तो Compose dependency failed to start: container zitadel-zitadel-api-1 is unhealthy के साथ रुक जाता है और docker compose logs zitadel-api में कारण मिलता है। Container का नाम project के आधार पर रखा जाता है। Shipped compose file इसे top-level name: zitadel से स्वयं set करती है, इसलिए directory name दिखाई नहीं देता। पहली बार start करने पर कारण आम तौर पर masterkey की length या database DSN होता है।
https://auth.example.com/ui/console पर login करें, password बदलें, फिर कुछ और बनाने से पहले उस account के लिए दूसरा factor enable करें। प्रत्येक ZITADEL_FIRSTINSTANCE_* value केवल पहले instance के create होने के दौरान लागू होती है। Instance बनने के बाद इन्हें edit करने से बिल्कुल कोई प्रभाव नहीं पड़ता।
पासवर्ड रीसेट काम क्यों नहीं करता जब तक SMTP ठीक से न चले
एक identity provider जो ईमेल नहीं भेज सकता, वह इस तरह से खराब होता है कि यह हफ्तों तक पता नहीं चलता। Zitadel उपयोगकर्ता आमंत्रणों, पता सत्यापन, पासवर्ड रीसेट लिंक, वन-टाइम कोड और डोमेन क्लेम नोटिस के लिए ईमेल भेजता है। यदि कोई SMTP provider कॉन्फ़िगर नहीं है, तो भी Console यह रिपोर्ट करता है कि कार्य पूरा हो गया है, और संदेश notification processing में चला जाता है, लेकिन उसे भेजने के लिए कोई जगह नहीं होती। v4.20.0 में, notifications डिफ़ॉल्ट रूप से legacy mode का उपयोग करती हैं (LegacyEnabled: true), जो parallel worker की MaxAttempts: 3 और MaxTtl: 5m सेटिंग्स को अनदेखा कर देता है। ये मान डिफ़ॉल्ट notification retry व्यवहार का वर्णन नहीं करते हैं। लिंक का इंतज़ार कर रहे व्यक्ति को कुछ भी पता नहीं चलता।
इसे Console में, https://auth.example.com/ui/console/settings पर instance settings के अंतर्गत कॉन्फ़िगर करें। SMTP provider फॉर्म में भेजने वाले का ईमेल पता, भेजने वाले का नाम, host और port, एक user, एक SMTP password और एक TLS toggle मांगा जाता है। सेव करने से पहले उस फॉर्म में टेस्ट बटन का उपयोग करें, क्योंकि यह एक वास्तविक संदेश भेजता है: यह या तो पहुँचता है या नहीं। provider को सक्रिय करें ताकि Zitadel इसका उपयोग मेल भेजने के लिए करे।
पर्यावरण चर (environment variables) का एक संबंधित सेट है, ZITADEL_DEFAULTINSTANCE_SMTPCONFIGURATION_SMTP_HOST और इसके साथी। ये तब लागू होते हैं जब कोई instance बनाया जाता है। पहले से चल रहे stack पर इनका कोई प्रभाव नहीं पड़ता, इसलिए मौजूदा instance के लिए Console ही सही जगह है।
VPS से डिलीवरी के बारे में दो बातें, क्योंकि यहीं पर यह आमतौर पर विफल होता है। relay चुनने से पहले अपने provider की outbound SMTP नीति की जाँच करें: DigitalOcean डिफ़ॉल्ट रूप से Droplets पर port 25, 465 और 587 को ब्लॉक करता है, इसलिए port 587 एक सार्वभौमिक समाधान नहीं है। ऐसे port पर एक authenticated relay का उपयोग करें जिसकी आपका provider अनुमति देता है। और भेजने वाले डोमेन के लिए SPF (sender policy framework) और DKIM (domainkeys identified mail) रिकॉर्ड प्रकाशित करें, अन्यथा रीसेट लिंक spam में चला जाएगा, जो उपयोगकर्ता को बिल्कुल वैसा ही लगेगा जैसे मेल कभी भेजा ही नहीं गया।
v4.20.0 पर, outbound SMTP TLS कनेक्शन compromised eMudhra intermediate CAs के माध्यम से certificate chains को अस्वीकार कर देते हैं। प्रभावित relay को एक प्रतिस्थापन certificate की आवश्यकता होती है।
किसी को भी आमंत्रित करने से पहले इसे सिद्ध करें। एक अस्थायी user बनाएँ, पासवर्ड रीसेट के लिए कहें, और देखें कि संदेश आता है या नहीं। यदि ऐसा नहीं होता है, तो docker compose logs -f zitadel-api SMTP विफलता का नाम बताता है। SMTP password डेटाबेस में एन्क्रिप्टेड रूप में संग्रहीत होता है, जो एक और चीज़ है जिसे masterkey आपके लिए सुरक्षित रखता है।
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 के साथ ऑफसाइट भेजें, जो इसे एन्क्रिप्ट और डुप्लीकेट हटाकर स्टोर करता है:
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 केवल पहले दिन, एक बार चलता है। डंप और अंतिम दो कमांड्स को /usr/local/bin/zitadel-backup.sh में डालें और इसे हर रात चलाएं:
0 3 * * * /usr/local/bin/zitadel-backup.sh.env और आपके द्वारा उपयोग की जाने वाली प्रत्येक compose फाइल का बैकअप git में रखें। 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_testeventstore स्कीमा में टेबल्स की सूची का मतलब है कि डंप सही है। यदि यह एरर आता है कि स्कीमा मौजूद नहीं है, तो इसका मतलब है कि डंप सही नहीं है, और आपने यह उस दिन पता लगा लिया है जब इसका कोई नुकसान नहीं है। Compose स्टैक के बैकअप और अपग्रेड का सामान्य पैटर्न यहाँ लगभग बिना किसी बदलाव के लागू होता है, और masterkey को उसी आर्काइव से बाहर रखना ही Zitadel के लिए एकमात्र विशेष हिस्सा है।
Instance खोए बिना Zitadel को upgrade करें
Upgrade में .env में version bump करने के बाद दो commands चलती हैं:
docker compose pull
docker compose up -d --waitकिसी ऐसी instance पर इसे चलाने से पहले समझें कि दूसरी command क्या करती है, जहाँ लोग login करते हैं। Container की command start-from-init है। यह serving शुरू करने से पहले init और setup phases चलाती है। Setup phase में database migrations होती हैं। इसलिए version bump पर container start होते समय live database के विरुद्ध schema migrations unattended तरीके से चलती हैं, जबकि --wait healthcheck का इंतजार करता रहता है। इसी कारण ऊपर दिया गया restore test optional नहीं है।
Upgrade से ठीक पहले fresh dump लें। पिछली रात का dump अलग चीज़ है।
v4.20.3 में चल रहे external identity provider sign-ins को फिर से शुरू करना होगा और unredeemed Login V1 authorization codes एक बार अस्वीकार किए जाएँगे। Custom login UIs को OIDC या SAML requests पूरी करने के लिए session.link permission चाहिए। Upgrade से पहले उनके service user को IAM_LOGIN_CLIENT grant करें। Shipped Login V2 service user के पास यह role पहले से है। Session API के password checks अब user की organisation login policy लागू करते हैं। इसलिए username/password login disable करने वाली organisations को users को अपने identity provider पर भेजना होगा।
Major version को skip न करें। v3 से v4 पर जाने से पहले v3.4.1 या उसके बाद के version पर जाएँ। v4 में OIDC web keys अनिवार्य हैं और legacy signing path हटा दिया गया है। इसलिए यदि आपकी v3 instance में web keys कभी enabled नहीं थीं, तो upgrade के बाद पुरानी legacy keys से signed tokens verify नहीं किए जा सकेंगे। Zitadel की technical advisory A-10017 के अनुसार मौजूदा JWT access tokens और ID tokens तुरंत invalid हो सकते हैं और users को फिर से sign in करना पड़ सकता है। इसका समाधान v3.4.1 या उसके बाद के version से होकर upgrade करना है और upgrade से पहले legacy-signed tokens तथा sessions को expire होने देना है। दूसरा विकल्प planned re-login window स्वीकार करना है। यदि आप पहले से v3.4.1 या उसके बाद का version चला रहे हैं और web keys enabled होने के बाद पर्याप्त समय बीत चुका है, तो advisory के अनुसार किसी action की आवश्यकता नहीं है।
docker compose logs -f zitadel-api से setup phase को monitor करें। बड़े eventstore पर migrations में कई minutes लग सकते हैं। Traefik healthcheck pass होने तक API पर route नहीं करेगा, इसलिए उस अवधि में site down रहेगी। इसकी योजना पहले बनाएँ, बाद में इसका पता न चले।
Rollback केवल पुराना tag वापस रखने से नहीं होता। Migrations चलने के बाद पुराना binary मिलने वाले schema को समझ नहीं पाता। इसलिए rollback का अर्थ dump restore करना है। Instance में वास्तविक users आ जाने के बाद docker-compose.prodlike.yml पर जाएँ। यह overlay init और setup को start से अलग steps के रूप में चलाता है। इससे migration container restart का side effect नहीं रहती, बल्कि ऐसी प्रक्रिया बन जाती है जिसे आप स्वयं trigger और monitor कर सकते हैं।
अपने नए identity provider को कहाँ पॉइंट करें
Console में, एक project बनाएँ और उसके अंदर एक application बनाएँ। किसी भी आधुनिक उपयोग के लिए OIDC चुनें, और Zitadel आपको एक client ID, एक client secret और https://auth.example.com/.well-known/openid-configuration पर एक discovery document देगा। single sign-on का समर्थन करने वाले अधिकांश self-hosted software को ठीक इन्हीं की आवश्यकता होती है।
बहुत से software इसका समर्थन नहीं करते हैं, या केवल paid tier में ही इसका समर्थन करते हैं। पहले मामले के लिए, app के सामने oauth2-proxy किसी भी HTTP service को ऐसी चीज़ में बदल देता है जिसे Zitadel सुरक्षित रख सके। दूसरे मामले के लिए, self-hosted apps में SSO tax को पढ़ना उपयोगी है, इससे पहले कि आप किसी ऐसे feature के आधार पर migration की योजना बनाएँ जिसके लिए आपने भुगतान नहीं किया है।
FAQ
self-hosted Zitadel के लिए कितनी RAM और CPU की आवश्यकता होती है?
Zitadel की production guide के अनुसार, Zitadel को स्वयं लगभग 0.5 GB RAM की आवश्यकता होती है और यह एक CPU core से कम पर भी चल सकता है, हालांकि पासवर्ड हैशिंग के लिए 4 cores उपलब्ध रखने की अनुशंसा की जाती है। PostgreSQL के लिए संसाधन अलग से निर्धारित किए जाते हैं, जो प्रति 100 अनुरोध प्रति सेकंड लगभग एक core और प्रति core 4 GB RAM के बराबर होते हैं। गाइड में दिए गए बड़े आंकड़े तीन-नोड वाले high-availability cluster में प्रति नोड के लिए हैं: प्रत्येक के लिए 4 cores और 16 GB, या log collection और metrics के बिना लगभग 4 cores और 8 GB। Compose quickstart में कम से कम 2 GB की मांग की गई है, जो इसे आज़माने के लिए पर्याप्त है, लेकिन यह उस डेटाबेस के लिए बहुत कम जगह छोड़ता है जिस पर अन्य सिस्टम सेवाएं निर्भर करती हैं।
यदि मैं Zitadel masterkey खो दूँ तो क्या होगा?
इसके साथ एन्क्रिप्ट की गई हर चीज़ एन्क्रिप्टेड ही रहेगी। Identity provider credentials, SMTP पासवर्ड और one-time-password seeds को डिक्रिप्ट नहीं किया जा सकेगा, और key को बाद में बदला नहीं जा सकता। केवल एक database dump से काम करने वाला instance रिस्टोर नहीं किया जा सकता, क्योंकि dump में ciphertext होता है और कोई key नहीं होती। Masterkey को एक password manager में रखें, और उसे उस बैकअप से अलग जगह रखें जिसमें dump मौजूद है। यदि दोनों खो जाते हैं, तो instance को शुरू से फिर से बनाना ही एकमात्र विकल्प बचता है।
Zitadel पासवर्ड रीसेट ईमेल कभी क्यों नहीं पहुँचते?
इसका कारण यह है कि कोई SMTP provider कॉन्फ़िगर नहीं किया गया है, या कॉन्फ़िगर किया गया provider ईमेल डिलीवर नहीं कर पा रहा है। Zitadel v4.20.0 डिफ़ॉल्ट रूप से legacy notification processing का उपयोग करता है, इसलिए parallel worker की तीन-प्रयास और पाँच-मिनट वाली सेटिंग्स को अनदेखा कर दिया जाता है। Instance सेटिंग्स के अंतर्गत SMTP provider को कॉन्फ़िगर करें और उस फॉर्म में दिए गए टेस्ट बटन का उपयोग करें, जो एक वास्तविक संदेश भेजता है। Provider को सक्रिय करें, ऐसे पोर्ट पर authenticated relay का उपयोग करें जिसकी अनुमति आपका VPS provider देता है, और भेजने वाले डोमेन के लिए SPF और DKIM रिकॉर्ड प्रकाशित करें ताकि मेल को स्पैम के रूप में फ़िल्टर न किया जाए।
क्या मैं इंस्टॉलेशन के बाद Zitadel external domain बदल सकता हूँ?
हाँ, लेकिन केवल .env को एडिट करके नहीं। ZITADEL_EXTERNALDOMAIN, ZITADEL_EXTERNALPORT और ZITADEL_EXTERNALSECURE को बदलें, और फिर Zitadel को अपना setup phase फिर से चलाने दें ताकि वह बदलाव को लागू कर सके। आपके द्वारा पहले से रजिस्टर किए गए applications अपने पुराने redirect URIs को बनाए रखते हैं और उन्हें मैन्युअल रूप से अपडेट करना होगा। साथ ही, कोई भी अनुरोध जिसका Host हेडर Zitadel द्वारा ज्ञात डोमेन से मेल नहीं खाता है, उसे Instance not found रिस्पॉन्स मिलेगा। पहली बार शुरू करने से पहले ही अंतिम नाम चुन लेने से इन सभी समस्याओं से बचा जा सकता है।