Docker দিয়ে VPS-এ Zitadel self-host করার নিয়ম
Zitadel-এর জন্য প্রায় 512 MB RAM লাগে। এক VPS-এ PostgreSQL, masterkey, TLS, SMTP ও backup সেটআপ করুন এবং upgrade-এ database-এ কী বদলায় জানুন।
VPS-এ Zitadel self-host করতে যা প্রয়োজন
VPS-এ Zitadel self-host করতে আপনার একটি Docker host, সেটির দিকে নির্দেশ করা একটি public DNS name, PostgreSQL এবং উভয়ের জন্য পর্যাপ্ত CPU ও RAM প্রয়োজন। Zitadel-এর production guide অনুযায়ী, শুধু application-এর জন্য প্রায় 512 MB RAM এবং 1 CPU core-এর কম প্রয়োজন। Database এবং password hashing-এর কারণে resource usage বাড়ে। Zitadel একটি identity provider। এটি OIDC (OpenID Connect) এবং SAML (security assertion markup language)-এর মাধ্যমে token জারি করে, যাতে আপনার অন্যান্য service-কে আলাদা user list সংরক্ষণ করতে না হয়। Installation-টি একটি curl এবং একটি docker compose up। এটি নির্ভরযোগ্যভাবে চালু থাকবে কি না, তা নির্ধারণ করে masterkey, database user, SMTP (simple mail transfer protocol), backup এবং প্রথম upgrade।
নিচের সবকিছু Ubuntu 24.04, Compose plugin version 2.24.4 বা পরবর্তী সংস্করণসহ Docker Engine 24 বা পরবর্তী সংস্করণ এবং ইতিমধ্যে server-এ resolve হওয়া auth.example.com-এর মতো একটি name ধরে নেওয়া হয়েছে। TLS overlay-গুলো !override ব্যবহার করে, যার জন্য ওই Compose version প্রয়োজন।
Zitadel-এর কতটা VPS দরকার?
Zitadel-এর ডকুমেন্টেশনের 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-এর কম ব্যবহার করেও চলতে পারে। CPU core-গুলো password hashing-এর জন্য প্রয়োজন। এই কাজটি ইচ্ছাকৃতভাবে ধীর, তাই একসঙ্গে অনেক login এলে CPU usage হঠাৎ বেড়ে যায়। এ কারণে guide-এ 4 CPU core উপলব্ধ রাখার সুপারিশ করা হয়েছে। PostgreSQL খরচের অন্য অংশ: একই guide-এ প্রতি 100 requests per second-এর জন্য প্রায় 1 core এবং প্রতি core-এর জন্য 4 GB RAM হিসাব করা হয়েছে।
বড় দুটি সারি একক সার্ভারের সংখ্যা নয়। ন্যূনতম high-availability setup-এর জন্য guide-এ তিনটি node-এর cluster সুপারিশ করা হয়েছে। প্রতিটি node-এ 4 core এবং 16 GB থাকবে। Log collection এবং metrics বাদ দিলে প্রতি node-এ এটি প্রায় 4 core এবং 8 GB-এ কমানো যায়। একক node-এর জন্য guide-এ কোনো sizing দেওয়া হয়নি।
তাই 2 GB VPS এই stack চালু করতে পারবে। তবে বাস্তব traffic শুরু হলে database-এর জন্য guide-এ যে বাজেট ধরা হয়েছে, এর তুলনায় এটি অনেক কম। Login হলো সেই service, যার ওপর অন্য সব service নির্ভর করে। এটি বন্ধ থাকলে, এর ওপর trust করা কোনো service কাউকে প্রবেশ করতে দেয় না। Authentication-এর জন্য guide-এ database এবং hashing-এর যে বাজেট ধরা হয়েছে, তা আপনার খরচসীমার বেশি বলে সিদ্ধান্ত নেওয়া যুক্তিসঙ্গত। Migration-এর পরে সিদ্ধান্ত নেওয়ার তুলনায় এখন এই সিদ্ধান্ত নেওয়া অনেক সস্তা। Keycloak, Authentik এবং Zitadel-এর তুলনা-এ প্রতিটির memory এবং operational work-এর খরচ আলোচনা করা হয়েছে, আর self-hosted Authentik server ছোট সার্ভারের জন্য সাধারণত ব্যবহৃত সমাধান।
Stack সংগ্রহ করুন এবং version নির্দিষ্ট করুন
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-এ আপনি বাস্তবে চালাবেন এমন চারটি service সংজ্ঞায়িত করা আছে। Traefik হলো reverse proxy: এটি path অনুযায়ী route করে এবং নিচের 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 profile-এর অধীনে রয়েছে এবং আপনি সক্রিয় না করা পর্যন্ত বন্ধ থাকে।
এখনই docker compose up চালাবেন না। প্রথমবার start হলে instance তৈরি হয়, এবং নিচের কয়েকটি setting পরে অতিরিক্ত কাজ ছাড়া পরিবর্তন করা যায় না।
আপনি কপি করা .env নিজস্ব image tag নির্দিষ্ট করে:
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-এ নির্দিষ্ট version-এর চেয়ে চারটি minor version এগিয়ে। v4.20.0-এর আগের release, 15 October 2026-এর v4.19.5, Zitadel-এর technical advisory A-10018-এর আওতায় পড়া প্রথম version: প্রভাবিত list endpoint-গুলোতে v1 এবং v2 API এখন default ও maximum limit প্রয়োগ করে। তাই limit ছাড়া list করা client আর সব result পায় না এবং pagination করতে হয়। Maximum-এর চেয়ে বেশি চাওয়া request প্রত্যাখ্যান করা হয়। v4.20.0-সহ পরবর্তী প্রতিটি release-এ এই পরিবর্তন রয়েছে। আপনি যে version চালাতে চান, ZITADEL_VERSION-এ সেটি নির্দিষ্ট করুন এবং সর্বশেষ version অনুসরণ না করে v4 line-এ থাকুন। হাতে version বেছে নিলে v4.18.0 বাদ দিন: release notes অনুযায়ী ওই version-এ setup step ব্যর্থ হয় এবং তার বদলে v4.19.0 ব্যবহার করতে বলা হয়েছে। উপরের curl docker-compose.yml-কে main branch থেকে আনে, যেখানে কোনো version pin করা নেই। তাই উভয় file-এর আপনার কপি একটি git repository-তে commit করুন। তা না হলে পরের মাসে নতুন box-এ একই command চালালে ভিন্ন file পাবেন এবং কী পরিবর্তন হয়েছে তা জানতে পারবেন না।
openssl rand -base64 32 দিয়ে তৈরি random value ব্যবহার করে .env-এর LOGIN_SESSION_COOKIE_SECRET প্রতিস্থাপন করুন। Login UI এটি session cookie sign করতে ব্যবহার করে। v4.19.5 release notes-এ example value রেখে না দেওয়ার বিষয়ে স্পষ্টভাবে সতর্ক করা হয়েছে।
Postgres-এর জন্য আলাদা user এবং শক্তিশালী password দিন
সরবরাহ করা .env superuser হিসেবে Zitadel-কে PostgreSQL-এর সঙ্গে সংযুক্ত করে, যার password হলো postgres:
POSTGRES_ADMIN_USER=postgres
POSTGRES_ADMIN_PASSWORD=postgres
ZITADEL_DATABASE_POSTGRES_DSN=postgresql://postgres:postgres@postgres:5432/zitadel?sslmode=disableএখানে hardening ধাপে একটি সমস্যা আছে। Zitadel-এর documentation-এ POSTGRES_ZITADEL_PASSWORD-কে .env-এর শেষে যোগ করতে বলা হয়েছে। কিন্তু মূল docker-compose.yml কখনো ওই variable পড়ে না। তাই এটি সেট করলেও কোনো পরিবর্তন হয় না। শুধু POSTGRES_ADMIN_PASSWORD পরিবর্তন করলে connection ভেঙে যায়। কারণ password-টি DSN (data source name) string-এর মধ্যেও সরাসরি লেখা আছে। DSN-ই নির্ধারণ করে Zitadel কীভাবে সংযুক্ত হবে।
.env.example-এর comment-এ বিষয়টি স্পষ্টভাবে বলা আছে। DSN configure করা থাকলে Zitadel ওই user-কে সরাসরি ব্যবহার করে এবং আপনার জন্য unprivileged user তৈরি করে না। তাই প্রথমবার start করার আগেই role-টি তৈরি থাকতে হবে। Role-এর জন্য একটি password generate করুন। Postgres start করার আগে .env-এ আলাদা একটি random password দিয়ে POSTGRES_ADMIN_PASSWORD সেট করুন। এরপর Postgres আলাদাভাবে start করে role-টি তৈরি করুন। Postgres image খালি data directory initialize করার সময়ই ওই admin password প্রয়োগ করে। পরে .env পরিবর্তন করলে বিদ্যমান database password পরিবর্তিত হয় না।
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 call-গুলো container-এর ভেতরে তার local socket ব্যবহার করে চলে। Official Postgres image ওই socket connection-এ trust করে। তাই password চাওয়া হয় না। গুরুত্বপূর্ণ বিষয় হলো ownership। Zitadel-এর init phase নিজস্ব schema (eventstore, projections, system) এবং table তৈরি করে। Database ownership ওই role-কে schema bootstrap করার জন্য প্রয়োজনীয় CREATE privilege দেয়। PostgreSQL 15-এ public schema-তে CREATE permission পরিবর্তন করা হয়েছে। এটি আলাদা বিষয় এবং এর অর্থ Zitadel-এর schema bootstrap ব্যর্থ হবে না।
এখন DSN-কে নতুন role-এর দিকে নির্দেশ করুন। Postgres start করার আগে যে admin password সেট করেছিলেন, সেটিই রেখে দিন:
POSTGRES_ADMIN_PASSWORD=a-32-character-random-string
ZITADEL_DATABASE_POSTGRES_DSN=postgresql://zitadel:the-password-you-generated@postgres:5432/zitadel?sslmode=disablesslmode=disable private Compose network-এ database connection encryption ছাড়াই রাখে। এর port কখনো host-এ publish করা হয় না। Production database connection-এর জন্য Zitadel-এর database guide TLS ব্যবহারের সুপারিশ করে। প্রথমবার সম্পূর্ণভাবে start হওয়ার পরে role-টি সত্যিই নিজের data-এর owner কি না যাচাই করুন:
docker compose exec -T postgres psql -U zitadel -d zitadel -c '\dn'এতে একটি eventstore schema, একটি projections schema এবং একটি system schema তালিকাভুক্ত হওয়ার কথা। এই schema-গুলো না থাকলে init phase ওই ধাপ পর্যন্ত পৌঁছায়নি। API container-এর log-এ কারণটি উল্লেখ থাকবে।
মাস্টার কী এবং এটি হারালে কী ক্ষতি হয়
Zitadel সংরক্ষণ করার আগে গোপন তথ্যগুলো encrypt করে: identity provider credential, SMTP password, one-time-password seed এবং machine key। masterkey এগুলো সব unlock করে। এটি ঠিক 32 bytes-এর এবং documentation-এ পরিণতি স্পষ্টভাবে বলা আছে: encrypted data-তে access হারানো ছাড়া এটি পরিবর্তন করা যায় না।
একটি masterkey তৈরি করুন এবং .env-এর placeholder line-টি প্রতিস্থাপন করুন:
tr -dc A-Za-z0-9 </dev/urandom | head -c 32; echoদ্বিতীয় একটি line যোগ না করে ZITADEL_MASTERKEY=MasterkeyNeedsToHave32Characters line-টি সম্পাদনা করুন। একই key একাধিকবার সংজ্ঞায়িত হলে Compose শেষ সংজ্ঞাটি ব্যবহার করে। তাই শেষে আরেকটি line যোগ করলেও কাজ হবে, কিন্তু একই file-এ দুটি masterkey line থাকলে পরবর্তী পাঠকের জন্য বিভ্রান্তির কারণ হবে।
এখন ভাবুন, key-টি কোথায় থাকে। compose file এভাবে API container চালু করে:
command: start-from-init --masterkey "${ZITADEL_MASTERKEY}"তাই masterkey container-এর command line-এ থাকে। Docker socket-এ access আছে এমন যে কেউ docker inspect ব্যবহার করে এটি দেখতে পারে। একক administrator-যুক্ত VPS-এ এটি গ্রহণযোগ্য trade-off হতে পারে। .env-এর mode-ই disk-এ থাকা key-টিকে সুরক্ষিত রাখে। এটি গ্রহণযোগ্য না হলে key-টি file হিসেবে mount করুন এবং পরিবর্তে --masterkeyFile /run/secrets/zitadel-masterkey ব্যবহার করুন। এতে process argument-এর বাইরে value রাখা হয়।
প্রথমবার start করার আগে masterkey-টি password manager-এ copy করে রাখুন। এটি database dump-এ থাকে না। তাই অন্য masterkey ব্যবহার করে dump restore করলে এমন একটি instance তৈরি হবে, যা নিজের secrets read করতে পারবে না। dump রাখা archive-এর বাইরে key-টি সংরক্ষণ করুন, যাতে একটি চুরি হওয়া backup-এ encrypted data এবং সেটি unlock করার key—দুটিই না থাকে।
প্রথমবার চালু করার আগে বাহ্যিক ডোমেইন নির্ধারণ করুন
ZITADEL_DOMAIN, container-এর মধ্যে .env-এ ZITADEL_EXTERNALDOMAIN-এর মান পাঠায়, এবং এটিই আপনার ব্যবহারকারীরা টাইপ করবেন। Zitadel এটি থেকে OIDC issuer, login interface-এর base URI, SAML endpoint এবং প্রথম admin-এর login name নির্ধারণ করে। তাই এটি শুধু নামমাত্র কোনো সেটিং নয়।
ZITADEL_DOMAIN=auth.example.com
ZITADEL_EXTERNALPORT=443
ZITADEL_EXTERNALSECURE=trueআপনি কোন instance-এর সঙ্গে কথা বলছেন, তা Zitadel Host header থেকে নির্ধারণ করে। ওই header-এর মান Zitadel-এর পরিচিত কোনো domain-এর সঙ্গে না মিললে প্রতিটি request একই উত্তর পায়:
ID=QUERY-1kIjX Message=Instance not foundএই error দেখলে দুটি বিষয় পরীক্ষা করুন। হয় ZITADEL_DOMAIN-এর মান আপনি যে name-এ যাচ্ছেন তার সঙ্গে মেলে না, অথবা সামনের proxy Host-কে upstream address-এ পরিবর্তন করছে। name-এর পরিবর্তে server-এর IP address-এ গেলে একই error দেখা যায়।
আপনি পরে এই মানগুলো পরিবর্তন করতে পারেন। পরিবর্তন কার্যকর করতে Zitadel-কে তার setup phase আবার চালাতে হবে। ইতিমধ্যে নিবন্ধিত প্রতিটি application-এর পুরোনো redirect URI থেকে যাবে। তাই এখনই চূড়ান্ত name বেছে নেওয়া পরে পরিবর্তন করার তুলনায় অনেক সহজ।
Let's Encrypt overlay দিয়ে TLS termination
একটি public domain-এর জন্য Zitadel-এর Let's Encrypt overlay যোগ করুন। এটি Traefik-কে ACME (automatic certificate management environment) HTTP challenge ব্যবহার করার জন্য পরিবর্তন করে এবং প্রকাশিত port-গুলোকে 80 ও 443 দিয়ে প্রতিস্থাপন করে। তাই এই server-এ অন্য কোনো service 80 বা 443 port ব্যবহার করতে পারবে না।
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 termination করেন, তাহলে docker-compose.mode-external-tls.yml ব্যবহার করুন এবং আপনার proxy যে range থেকে request পাঠায়, তা দিয়ে TRAEFIK_TRUSTED_IPS সেট করুন। ওই তালিকায় থাকা address থেকেই আসা X-Forwarded-* header Traefik গ্রহণ করে। এই overlay Zitadel-এর external URL এবং login URL-গুলোকে HTTPS হিসেবে স্পষ্টভাবে সেট করে।
একটি upstream proxy-এর দুটি কাজ Zitadel কঠোরভাবে প্রত্যাশা করে। এটিকে backend-এর সঙ্গে HTTP/2 ব্যবহার করতে হবে, কারণ API হলো gRPC। একই সঙ্গে এটিকে Host এবং X-Forwarded-Proto: https অপরিবর্তিত অবস্থায় pass through করতে হবে। এই 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 placeholder-গুলো nginx যে address-এ পৌঁছাতে পারে, সেগুলো দিয়ে প্রতিস্থাপন করুন। আপনি যদি Zitadel-কে 443 ছাড়া অন্য কোনো port-এ পরিবেশন করেন, তাহলে grpc_set_header Host $host:$server_port; ব্যবহার করুন, যাতে header-এর সঙ্গে port-ও পাঠানো হয়। বাকি অংশ একটি সাধারণ virtual host। Zitadel-নির্দিষ্ট নয় এমন অংশগুলো nginx reverse proxy configuration line by line পড়ুন নির্দেশিকায় ব্যাখ্যা করা হয়েছে।
প্রথম 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 হলো Password1!। Zitadel-এর upstream default প্রথম login-এ password change বাধ্যতামূলক করে, কিন্তু সরবরাহ করা compose file সেই default override করে:
ZITADEL_FIRSTINSTANCE_ORG_HUMAN_PASSWORDCHANGEREQUIRED: falseএই line-টি .env থেকে পড়ার বদলে docker-compose.yml-এ hardcode করা আছে। তাই নিজের value একটি ছোট overlay file-এ রাখুন। Fileটির নাম দিন 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"কোনো -f flag ছাড়া চালালে Compose নিজে থেকেই শুধু docker-compose.override.yml load করে। কিন্তু Zitadel-এর guide-এর প্রতিটি command-এ -f দেওয়া আছে, ফলে এই আচরণ বন্ধ হয়ে যায়। ক্রমশ বাড়তে থাকা flag-এর তালিকা বারবার লেখার বদলে 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 --waitHealthcheck pass না হওয়া পর্যন্ত --wait command-টি ধরে রাখে। API container কখনো সেই অবস্থায় পৌঁছাতে না পারলে Compose dependency failed to start: container zitadel-zitadel-api-1 is unhealthy দিয়ে থেমে যায়, এবং কারণটি docker compose logs zitadel-api-এ থাকে। Container-এর নাম project অনুযায়ী নির্ধারিত হয়। সরবরাহ করা compose file নিজেই top-level name: zitadel দিয়ে এটি নির্ধারণ করে, তাই directory name দেখা যায় না। প্রথম start-এ সাধারণত masterkey-এর length অথবা database DSN কারণ হয়ে থাকে।
https://auth.example.com/ui/console-এ login করুন, password change করুন, তারপর অন্য কিছু তৈরি করার আগে ওই account-এর জন্য second factor চালু করুন। প্রতিটি ZITADEL_FIRSTINSTANCE_* value শুধু প্রথম instance তৈরির সময় প্রযোজ্য। Instance তৈরি হয়ে গেলে এগুলো edit করলেও কোনো প্রভাব পড়ে না।
SMTP কাজ না করা পর্যন্ত password reset কেন কোনো ফল দেয় না
যে identity provider email পাঠাতে পারে না, সেটি এমনভাবে নষ্ট থাকে যে কয়েক সপ্তাহ তা ধরা পড়ে না। Zitadel user invitation, address verification, password reset link, one-time code এবং domain claim notice-এর জন্য email পাঠায়। কোনো SMTP provider configure না থাকলে Console তবু action-টি সম্পন্ন হয়েছে বলে জানায়, এবং message notification processing-এ চলে যায়, কিন্তু পাঠানোর কোনো গন্তব্য থাকে না। v4.20.0-তে notification ডিফল্টভাবে legacy mode ব্যবহার করে (LegacyEnabled: true), যা parallel worker-এর MaxAttempts: 3 এবং MaxTtl: 5m setting উপেক্ষা করে। এই value-গুলো ডিফল্ট notification retry behavior নির্দেশ করে না। Link-এর জন্য অপেক্ষা করা ব্যক্তিকে কিছুই জানানো হয় না।
Console-এ instance settings-এর https://auth.example.com/ui/console/settings-এর অধীনে এটি configure করুন। SMTP provider form-এ sender email address, sender name, host ও port, user, SMTP password এবং TLS toggle চাওয়া হয়। Save করার আগে ওই form-এর test button ব্যবহার করুন, কারণ এটি বাস্তব message পাঠায়: message পৌঁছায়, অথবা পৌঁছায় না। Provider-টি activate করুন, যাতে Zitadel এটি ব্যবহার করে mail পাঠায়।
এর জন্য environment variable-এর একটি সমতুল্য set আছে, ZITADEL_DEFAULTINSTANCE_SMTPCONFIGURATION_SMTP_HOST এবং এর সমজাতীয় variable-গুলো। এগুলো instance তৈরির সময় প্রযোজ্য। ইতিমধ্যে চলমান stack-এ এগুলোর কোনো প্রভাব নেই। তাই existing instance-এর জন্য Console-ই সঠিক স্থান।
VPS থেকে delivery-এর ক্ষেত্রে দুটি বিষয় মনে রাখুন, কারণ সাধারণত এখানেই সমস্যা হয়। Relay বেছে নেওয়ার আগে আপনার provider-এর outbound SMTP policy পরীক্ষা করুন: DigitalOcean ডিফল্টভাবে Droplet-এ port 25, 465 এবং 587 block করে। তাই port 587 সর্বজনীন workaround নয়। Provider যে port অনুমতি দেয়, সেই port-এ authenticated relay ব্যবহার করুন। Sending domain-এর জন্য SPF (sender policy framework) এবং DKIM (domainkeys identified mail) record প্রকাশ করুন। তা না হলে reset link spam folder-এ চলে যেতে পারে। ব্যবহারকারীর কাছে এটি এমনই মনে হবে, যেন mail কখনো পাঠানো হয়নি।
v4.20.0-তে outbound SMTP TLS connection compromised eMudhra intermediate CA-এর মাধ্যমে তৈরি certificate chain প্রত্যাখ্যান করে। আক্রান্ত relay-এর replacement certificate প্রয়োজন।
কাউকে invite করার আগে এটি যাচাই করুন। একটি throwaway user তৈরি করুন, password reset-এর অনুরোধ করুন এবং message পৌঁছানো monitor করুন। Message না পৌঁছালে, docker compose logs -f zitadel-api SMTP failure-এর কারণ উল্লেখ করে। SMTP password database-এ encrypted অবস্থায় সংরক্ষিত হয়। এটি 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 stack ব্যাকআপ এবং আপগ্রেড করার সাধারণ নিয়ম এখানে প্রায় অপরিবর্তিতভাবে প্রযোজ্য, এবং masterkey-কে একই আর্কাইভের বাইরে রাখাটাই Zitadel-এর জন্য একমাত্র বিশেষ অংশ।
Instance না হারিয়ে Zitadel upgrade করুন
Upgrade হলো .env-এ version bump করার পর দুটি command চালানো:
docker compose pull
docker compose up -d --waitযে system-এ মানুষ login করে, সেখানে চালানোর আগে দ্বিতীয় command কী করে তা বুঝে নিন। Container-এর command হলো start-from-init। এটি serving শুরু করার আগে init এবং setup phase চালায়। Setup phase-এ database migration হয়। তাই version bump করলে container start-এর সময় live database-এ unattended অবস্থায় schema migration চলে, আর --wait healthcheck-এর জন্য অপেক্ষা করে। Restore test ঐচ্ছিক নয়—এর সম্পূর্ণ কারণ এটাই।
Upgrade-এর ঠিক আগে fresh dump নিন। গত রাতের dump একই জিনিস নয়।
v4.20.3-এ চলমান external identity provider sign-in পুনরায় শুরু করতে হবে এবং redeem না করা Login V1 authorization code একবার প্রত্যাখ্যাত হবে। Custom login UI-এর OIDC বা SAML request সম্পন্ন করতে session.link permission প্রয়োজন। Upgrade-এর আগে তাদের service user-কে IAM_LOGIN_CLIENT দিন। Shipped Login V2 service user-এর কাছে এই role আগে থেকেই আছে। Session API-এর password check এখন user-এর organisation login policy প্রয়োগ করে। তাই username/password login বন্ধ করা organisation-গুলোকে user-দের identity provider-এ পাঠাতে হবে।
Major version বাদ দিয়ে upgrade করবেন না। v3 থেকে v4-এ যাওয়ার আগে প্রথমে v3.4.1 বা পরবর্তী version-এ উঠুন। v4-এ OIDC web key বাধ্যতামূলক করা হয়েছে এবং legacy signing path সরিয়ে দেওয়া হয়েছে। তাই আপনার v3 instance-এ web key কখনও সক্রিয় না থাকলে upgrade-এর পরে পুরোনো legacy key দিয়ে sign করা token আর verify করা যাবে না। Zitadel-এর technical advisory A-10017 অনুযায়ী, বিদ্যমান JWT access token এবং ID token সঙ্গে সঙ্গে invalid হয়ে যেতে পারে এবং user-দের আবার sign in করতে হতে পারে। এর সমাধান হলো v3.4.1 বা পরবর্তী version দিয়ে ধাপে upgrade করা এবং v4-এ যাওয়ার আগে legacy-signed token ও session expire হতে দেওয়া, অথবা পরিকল্পিত re-login window গ্রহণ করা। আপনি যদি ইতিমধ্যে v3.4.1 বা পরবর্তী version চালান এবং web key সক্রিয় করার পর অপেক্ষা করে থাকেন, advisory অনুযায়ী কোনো action প্রয়োজন নেই।
docker compose logs -f zitadel-api দিয়ে setup phase monitor করুন। বড় eventstore-এ migration সম্পন্ন হতে কয়েক মিনিট লাগতে পারে। Healthcheck pass না করা পর্যন্ত Traefik API-তে route করবে না। তাই ওই সময় site down থাকবে। এটি আগে থেকে পরিকল্পনা করুন, পরে যেন অপ্রত্যাশিতভাবে না জানতে হয়।
Rollback মানে শুধু পুরোনো tag আবার বসানো নয়। Migration চলার পরে পুরোনো binary তার পাওয়া schema বুঝতে পারে না। তাই rollback করতে হলে dump restore করতে হয়। Instance-এ বাস্তব user যুক্ত হয়ে গেলে docker-compose.prodlike.yml-এ যান। এই overlay init এবং setup-কে start থেকে আলাদা step হিসেবে চালায়। ফলে migration container restart-এর পার্শ্বপ্রতিক্রিয়া হিসেবে না হয়ে আপনার নির্দিষ্ট ও monitored একটি কাজ হয়।
আপনার নতুন 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 সফটওয়্যার ঠিক এই তথ্যগুলোই চায়।
অনেক সফটওয়্যার এটি সমর্থন করে না, অথবা শুধুমাত্র পেইড টায়ারে এটি সমর্থন করে। প্রথম ক্ষেত্রের জন্য, অ্যাপের সামনে oauth2-proxy যেকোনো HTTP সার্ভিসকে এমন কিছুতে পরিণত করে যা Zitadel সুরক্ষিত রাখতে পারে। দ্বিতীয় ক্ষেত্রের জন্য, আপনি যে ফিচারের জন্য অর্থ প্রদান করেননি তার ওপর ভিত্তি করে কোনো migration পরিকল্পনা করার আগে self-hosted অ্যাপে SSO-এর খরচ বিষয়টি পড়ে নেওয়া বুদ্ধিমানের কাজ।
FAQ
একটি self-hosted Zitadel-এর জন্য কত RAM এবং CPU প্রয়োজন?
Zitadel-এর production guide অনুযায়ী, Zitadel-এর নিজের জন্য প্রায় 0.5 GB RAM প্রয়োজন এবং এটি 1টির কম CPU core-এ চলতে পারে। তবে password hashing-এর জন্য 4টি core available রাখার পরামর্শ দেওয়া হয়েছে। PostgreSQL-এর হিসাব আলাদাভাবে করা হয়: প্রতি 100 requests per second-এর জন্য আনুমানিক 1টি core এবং প্রতি core-এর জন্য 4 GB RAM। Guide-এ দেওয়া বড় সংখ্যাগুলো three-node high-availability cluster-এর প্রতিটি node-এর জন্য প্রযোজ্য: প্রতিটিতে 4টি core এবং 16 GB, অথবা log collection ও metrics ছাড়া প্রায় 4টি core এবং 8 GB। Compose quickstart-এ অন্তত 2 GB চাওয়া হয়। এটি পরীক্ষা করার জন্য যথেষ্ট, তবে যে database-এর ওপর সিস্টেমের অন্যান্য service নির্ভর করবে তার জন্য খুব কম অতিরিক্ত জায়গা থাকে।
আমি Zitadel-এর masterkey হারালে কী হবে?
এটি দিয়ে encrypted করা সবকিছু encrypted-ই থাকবে। Identity provider credentials, SMTP password এবং one-time-password seed decrypt করা যাবে না। পরে এই key পরিবর্তনও করা যায় না। শুধু database dump থাকলে কার্যকর instance পুনরুদ্ধার করা যায় না, কারণ dump-এ ciphertext থাকে, key থাকে না। masterkey-টি password manager-এ এবং dump রাখা backup-এর আলাদা জায়গায় সংরক্ষণ করুন। দুটিই হারিয়ে গেলে instance শুরু থেকে rebuild করাই একমাত্র উপায়।
Zitadel-এর password reset email কখনো পৌঁছায় না কেন?
কারণ কোনো SMTP provider configured নেই, অথবা configured provider message deliver করতে পারছে না। Zitadel v4.20.0 ডিফল্টভাবে legacy notification processing ব্যবহার করে। তাই parallel worker-এর three-attempt এবং five-minute settings উপেক্ষিত হয়। Instance settings-এর অধীনে SMTP provider configure করুন এবং সেই form-এর test button ব্যবহার করুন। এটি একটি বাস্তব message পাঠায়। Provider activate করুন, আপনার VPS provider অনুমোদিত port-এ authenticated relay ব্যবহার করুন, এবং sending domain-এর জন্য SPF ও DKIM record publish করুন, যাতে mail spam হিসেবে filter না হয়।
Install করার পরে কি Zitadel-এর external domain পরিবর্তন করা যায়?
হ্যাঁ, তবে শুধু .env edit করে নয়। ZITADEL_EXTERNALDOMAIN, ZITADEL_EXTERNALPORT এবং ZITADEL_EXTERNALSECURE পরিবর্তন করুন। এরপর Zitadel-কে setup phase আবার চালাতে দিন, যাতে পরিবর্তনটি প্রয়োগ হয়। আগে নিবন্ধিত applications-এ পুরোনো redirect URI থেকে যাবে এবং সেগুলো হাতে update করতে হবে। এছাড়া কোনো request-এর Host header Zitadel-এর পরিচিত কোনো domain-এর সঙ্গে না মিললে Instance not found ফেরত দেওয়া হবে। প্রথমবার start করার আগেই চূড়ান্ত নাম নির্বাচন করলে এসব সমস্যা এড়ানো যায়।