Samodzielna instalacja Zitadel na VPS przez Docker
Dowiedz się jak poprawnie skonfigurować Zitadel na własnym serwerze. Instrukcja obejmuje konfigurację PostgreSQL, masterkey, TLS, SMTP oraz bezpieczne wykonywanie aktualizacji.
Wymagania do samodzielnego hostowania Zitadel na VPS
Aby samodzielnie hostować Zitadel na VPS, potrzebujesz hosta Docker, publicznej nazwy DNS wskazującej na ten serwer, bazy PostgreSQL oraz wystarczającej ilości CPU i RAM dla obu tych komponentów. Przewodnik produkcyjny Zitadel określa zapotrzebowanie samej aplikacji na około 512 MB pamięci RAM i mniej niż jeden rdzeń CPU. Wraz z czasem rośnie zapotrzebowanie bazy danych oraz procesów haszowania haseł. Zitadel jest dostawcą tożsamości. Wydaje tokeny przez OIDC (OpenID Connect) oraz SAML (security assertion markup language), dzięki czemu inne usługi nie muszą utrzymywać własnych list użytkowników. Instalacja składa się z curl oraz docker compose up. Kluczowymi elementami decydującymi o stabilności są masterkey, użytkownik bazy danych, SMTP (simple mail transfer protocol), kopia zapasowa oraz pierwsza aktualizacja.
Wszystkie poniższe instrukcje zakładają użycie systemu Ubuntu 24.04, Docker Engine w wersji 24 lub nowszej z wtyczką Compose w wersji 2.24.4 lub nowszej oraz nazwy takiej jak auth.example.com, która już wskazuje na serwer. Nakładki TLS wykorzystują !override, co wymaga wspomnianej wersji Compose.
Jakich zasobów VPS wymaga Zitadel?
Szybki start z użyciem Compose w dokumentacji Zitadel wskazuje na zapotrzebowanie 2 GB pamięci RAM. Wartość ta dotyczy wyłącznie szybkiego uruchomienia. Przewodnik wdrożeniowy Zitadel dla środowisk produkcyjnych podaje inne liczby.
Dane, na których opiera się ten wykres
[
{
"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
}
]Są to zalecenia, a nie pomiary z działającego serwera. Należy traktować je jako szacunkowy zakres wymagań. Sam proces Zitadel jest lekki: przewodnik określa jego zapotrzebowanie na około 0.5 GB pamięci RAM i wskazuje, że może działać na mniej niż jednym rdzeniu procesora. Rdzenie są potrzebne do haszowania haseł, co jest celowo spowolnionym procesem, więc nagły wzrost liczby logowań powoduje skokowe obciążenie CPU. Przewodnik zaleca zapewnienie 4 rdzeni procesora na ten cel. PostgreSQL stanowi drugą część zapotrzebowania: ten sam przewodnik zakłada około jednego rdzenia na każde 100 żądań na sekundę oraz 4 GB pamięci RAM na rdzeń.
Dwa większe wiersze w tabeli nie dotyczą konfiguracji na pojedynczym serwerze. W przypadku minimalnego środowiska o wysokiej dostępności przewodnik zaleca klaster trzech węzłów, z których każdy posiada 4 rdzeni oraz 16 GB pamięci RAM. Wskazuje również, że można zredukować te wartości do około 4 rdzeni i 8 GB pamięci RAM na węzeł, jeśli zrezygnuje się z gromadzenia logów i metryk. Dokumentacja nie podaje wytycznych dla pojedynczego węzła.
Zatem VPS z 2 GB pamięci RAM uruchomi ten stos, jednak jest to wartość znacznie poniżej budżetu przewidzianego w przewodniku dla samej bazy danych w warunkach rzeczywistego ruchu. Logowanie to usługa, od której zależą wszystkie inne. Gdy jest niedostępna, żadna usługa korzystająca z niej nie pozwoli na dostęp użytkownikom. Decyzja o tym, że budżet zasobów dla bazy danych i haszowania jest zbyt wysoki jak na potrzeby uwierzytelniania, jest uzasadniona. Znacznie taniej jest podjąć ją teraz, niż po zakończeniu migracji. Porównanie Keycloak, Authentik i Zitadel omawia koszty pamięciowe i operacyjne każdego z tych rozwiązań, a samodzielnie hostowany serwer Authentik jest zazwyczaj wybierany w przypadku mniejszych maszyn.
Pobranie stosu i przypięcie wersji
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 .envTen plik definiuje cztery usługi, które zostaną uruchomione. Traefik pełni rolę reverse proxy: kieruje ruch według ścieżki i, wraz z poniższą nakładką, dokonuje terminacji TLS (transport layer security). zitadel-api to binarny plik Go działający na porcie 8080. zitadel-login to interfejs logowania serwowany pod /ui/v2/login. postgres przechowuje wszystkie dane. Pamięć podręczna Redis oraz kolektor OpenTelemetry znajdują się w tym samym pliku za profilami Compose i pozostają wyłączone, dopóki nie zostaną jawnie aktywowane.
Nie uruchamiaj jeszcze docker compose up. Pierwszy start tworzy instancję, a wielu poniższych ustawień nie można później zmienić bez dodatkowej pracy.
Skopiowany .env posiada przypięte własne tagi obrazów:
ZITADEL_VERSION=v4.16.0
TRAEFIK_IMAGE=traefik:v3.7.7
POSTGRES_IMAGE=postgres:17.10-alpineObecne wydanie v4 to v4.20.3, opublikowane 13 listopada 2026, o cztery wersje podrzędne nowsze niż przypięcie w dostarczonym pliku. Wydanie poprzedzające v4.20.0, czyli v4.19.5 z 15 października 2026, jest pierwszym objętym biuletynem technicznym Zitadel A-10018: dotyczy ono punktów końcowych list w API v1 i v2, które teraz stosują limity domyślne i maksymalne. Oznacza to, że klient pobierający listę bez limitu nie otrzymuje już wszystkich wyników i musi korzystać ze stronicowania, a żądanie przekraczające limit maksymalny jest odrzucane. Każde późniejsze wydanie, w tym v4.20.0, zawiera tę zmianę. Ustaw ZITADEL_VERSION na wersję, którą zamierzasz uruchomić, i pozostań w linii v4 zamiast śledzić najnowsze wydania. Pomiń v4.18.0, jeśli wybierasz wersję ręcznie: informacje o wydaniu wskazują, że krok konfiguracji w tej wersji kończy się niepowodzeniem i należy użyć v4.19.0. Powyższy curl pobiera docker-compose.yml z gałęzi main, która nie jest przypięta do żadnej wersji, dlatego zapisz swoją kopię obu plików w repozytorium git. W przeciwnym razie to samo polecenie wykonane na nowej maszynie w przyszłym miesiącu pobierze inny plik i nie będzie wiadomo, co uległo zmianie.
Zastąp LOGIN_SESSION_COOKIE_SECRET w .env losową wartością wygenerowaną przez openssl rand -base64 32. Interfejs logowania używa jej do podpisywania ciasteczek sesji, a informacje o wydaniu v4.19.5 wyraźnie ostrzegają przed pozostawieniem przykładowej wartości.
Nadanie Postgres własnego użytkownika i silnego hasła
Dostarczony .env łączy Zitadel z PostgreSQL jako superużytkownik, używając hasła postgres:
POSTGRES_ADMIN_USER=postgres
POSTGRES_ADMIN_PASSWORD=postgres
ZITADEL_DATABASE_POSTGRES_DSN=postgresql://postgres:postgres@postgres:5432/zitadel?sslmode=disableNa etapie utwardzania zabezpieczeń występuje pułapka. Dokumentacja Zitadel zaleca dopisanie POSTGRES_ZITADEL_PASSWORD do .env, jednak bazowy docker-compose.yml nie odczytuje tej zmiennej, więc jej ustawienie nie przynosi efektu. Samodzielna zmiana POSTGRES_ADMIN_PASSWORD powoduje zerwanie połączenia, ponieważ hasło jest zapisane bezpośrednio w ciągu DSN (data source name). DSN to parametr określający sposób nawiązywania połączenia przez Zitadel.
Komentarze w .env.example wyjaśniają to wprost: gdy DSN jest skonfigurowany, Zitadel używa wskazanego użytkownika bezpośrednio i nie tworzy konta z ograniczonymi uprawnieniami, dlatego rola musi istnieć przed pierwszym uruchomieniem. Należy wygenerować hasło dla roli, ustawić POSTGRES_ADMIN_PASSWORD na losowe hasło w .env przed uruchomieniem Postgres, a następnie uruchomić Postgres i utworzyć rolę. Obraz Postgres stosuje hasło administratora tylko podczas inicjalizacji pustego katalogu danych; zmiana .env w późniejszym czasie nie zmienia hasła w istniejącej bazie danych.
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;
SQLWywołania psql są wykonywane wewnątrz kontenera przez lokalny socket, któremu oficjalny obraz Postgres ufa, więc nie wymagają podania hasła. Kluczowe znaczenie ma własność. Faza inicjalizacji Zitadel tworzy własne schematy (eventstore, projections, system) oraz tabele. Własność bazy danych nadaje roli uprawnienie CREATE niezbędne do zainicjowania tych schematów. Zmiana w PostgreSQL 15 dotycząca uprawnień CREATE w schemacie public jest odrębna i nie oznacza, że inicjalizacja schematów Zitadel zakończy się niepowodzeniem.
Teraz należy wskazać DSN na nową rolę, zachowując hasło administratora ustawione przed uruchomieniem Postgres:
POSTGRES_ADMIN_PASSWORD=a-32-character-random-string
ZITADEL_DATABASE_POSTGRES_DSN=postgresql://zitadel:the-password-you-generated@postgres:5432/zitadel?sslmode=disablesslmode=disable pozostawia połączenie z bazą danych niezaszyfrowane w prywatnej sieci Compose; port ten nigdy nie jest publikowany na hoście. Przewodnik po bazie danych Zitadel zaleca stosowanie TLS dla produkcyjnych połączeń z bazą. Po pierwszym pełnym uruchomieniu należy sprawdzić, czy rola faktycznie jest właścicielem danych:
docker compose exec -T postgres psql -U zitadel -d zitadel -c '\dn'Polecenie to powinno wyświetlić schemat eventstore, schemat projections oraz schemat system. Jeśli tych schematów brakuje, faza inicjalizacji nie została ukończona, a dziennik kontenera API wskaże przyczynę.
Klucz główny i koszty jego utraty
Zitadel szyfruje sekrety przed ich zapisaniem: dane uwierzytelniające dostawców tożsamości, hasło SMTP, ziarna haseł jednorazowych oraz klucze maszynowe. Klucz główny (masterkey) odblokowuje wszystkie te dane. Ma on dokładnie 32 bajty, a dokumentacja jasno określa konsekwencje: nie można go zmienić bez utraty dostępu do zaszyfrowanych danych.
Wygeneruj klucz i zastąp nim linię zastępczą w .env:
tr -dc A-Za-z0-9 </dev/urandom | head -c 32; echoEdytuj linię ZITADEL_MASTERKEY=MasterkeyNeedsToHave32Characters zamiast dopisywać drugą. Docker Compose przyjmuje ostatnią definicję powtórzonego klucza, więc dopisanie zadziała, jednak plik zawierający dwie linie masterkey stanowi pułapkę dla kolejnego administratora.
Zastanów się teraz, gdzie ten klucz się znajduje. Plik Compose uruchamia kontener API w następujący sposób:
command: start-from-init --masterkey "${ZITADEL_MASTERKEY}"Klucz główny znajduje się zatem w linii poleceń kontenera, gdzie docker inspect ujawnia go każdemu, kto ma dostęp do Docker socket. Na serwerze VPS z jednym administratorem jest to akceptowalny kompromis, a uprawnienia pliku .env chronią go na dysku. Jeśli takie rozwiązanie jest nieakceptowalne, zamontuj klucz jako plik i użyj --masterkeyFile /run/secrets/zitadel-masterkey, co pozwoli uniknąć przekazywania wartości w argumentach procesu.
Skopiuj klucz główny do menedżera haseł przed pierwszym uruchomieniem. Nie pojawia się on w zrzucie bazy danych, więc zrzut przywrócony z innym kluczem głównym utworzy instancję, która nie będzie w stanie odczytać własnych sekretów. Przechowuj go w innym miejscu niż archiwum zawierające zrzut, aby kradzież kopii zapasowej nie oznaczała utraty zarówno zaszyfrowanych danych, jak i klucza do nich.
Ustawienie domeny zewnętrznej przed pierwszym uruchomieniem
ZITADEL_DOMAIN w .env zasila ZITADEL_EXTERNALDOMAIN w kontenerze i jest to nazwa, którą wpisują użytkownicy. Zitadel wywodzi z niej wystawcę OIDC, bazowy URI interfejsu logowania, punkty końcowe SAML oraz nazwę logowania pierwszego administratora, więc nie jest to ustawienie czysto kosmetyczne.
ZITADEL_DOMAIN=auth.example.com
ZITADEL_EXTERNALPORT=443
ZITADEL_EXTERNALSECURE=trueZitadel rozpoznaje, z którą instancją nawiązywane jest połączenie, na podstawie nagłówka Host. Jeśli nagłówek ten nie pasuje do znanej domeny, każde żądanie otrzymuje tę samą odpowiedź:
ID=QUERY-1kIjX Message=Instance not foundW przypadku wystąpienia tego błędu należy sprawdzić dwie kwestie. Albo ZITADEL_DOMAIN nie jest nazwą, pod którą przeglądarka uzyskuje dostęp do serwera, albo proxy znajdujące się przed aplikacją nadpisuje Host adresem upstream. Błąd ten pojawia się również w przypadku uzyskiwania dostępu do serwera poprzez adres IP zamiast nazwy domenowej.
Wartości te można zmienić w późniejszym czasie. Zitadel musi jednak ponownie uruchomić fazę konfiguracji, aby uwzględnić zmiany, a wszystkie zarejestrowane już aplikacje zachowają swoje stare URI przekierowań. Wybór docelowej nazwy na obecnym etapie jest znacznie mniej kosztowny niż późniejsza migracja.
Terminacja TLS za pomocą nakładki Let's Encrypt
Dla domeny publicznej należy dodać nakładkę Let's Encrypt dla Zitadel. Przełącza ona Traefik na wyzwanie HTTP ACME (automatic certificate management environment) i zastępuje opublikowane porty portami 80 oraz 443, co oznacza, że żadna inna usługa na serwerze nie może z nich korzystać.
curl -fsSLO https://raw.githubusercontent.com/zitadel/zitadel/main/deploy/compose/docker-compose.mode-letsencrypt.yml
echo 'LETSENCRYPT_EMAIL=ops@example.com' >> .envNakładka ustawia również ZITADEL_EXTERNALPORT: 443 oraz ZITADEL_EXTERNALSECURE: true w kontenerze API, dzięki czemu publiczny adres URL oraz adresy URL generowane wewnętrznie przez Zitadel są zgodne. Rekord A musi zostać poprawnie rozwiązany przed uruchomieniem, ponieważ w przeciwnym razie wyzwanie HTTP zakończy się niepowodzeniem.
Jeśli terminacja TLS odbywa się już na nginx lub na load balancerze, należy użyć docker-compose.mode-external-tls.yml i ustawić TRAEFIK_TRUSTED_IPS na zakresy adresów, z których wysyła ruch proxy. Traefik uwzględnia nagłówki X-Forwarded-* tylko z adresów znajdujących się na tej liście. Nakładka jawnie ustawia zewnętrzny adres URL Zitadel oraz adresy logowania na HTTPS.
Proxy nadrzędne ma dwa zadania, co do których Zitadel jest rygorystyczny. Musi ono obsługiwać protokół HTTP/2 w komunikacji z backendem, ponieważ API wykorzystuje gRPC. Musi również przekazywać nagłówek Host bez zmian, wraz z X-Forwarded-Proto: https. W przypadku tego stosu Compose, konfiguracja nginx przyjmuje następującą postać:
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;
}
}Należy zastąpić symbole zastępcze upstream adresami, do których nginx ma dostęp. Jeśli Zitadel jest udostępniany na porcie innym niż 443, należy użyć grpc_set_header Host $host:$server_port;, aby numer portu był przekazywany wraz z nagłówkiem. Reszta konfiguracji to standardowy wirtualny host, a konfiguracja reverse proxy nginx omówiona wiersz po wierszu opisuje elementy, które nie są specyficzne dla Zitadel.
Pierwszy administrator i wymuszenie zmiany hasła
Pierwsze uruchomienie tworzy jedną instancję, jedną organizację oraz jednego administratora. Nazwa użytkownika to zitadel-admin@ plus zitadel. plus Twoja domena zewnętrzna, więc dla ZITADEL_DOMAIN=auth.example.com jest to:
zitadel-admin@zitadel.auth.example.comHasło to Password1!, chyba że ustawiono własne. Domyślne ustawienie Zitadel wymusza zmianę hasła przy pierwszym logowaniu, a dostarczony plik compose nadpisuje tę wartość:
ZITADEL_FIRSTINSTANCE_ORG_HUMAN_PASSWORDCHANGEREQUIRED: falseTa linia jest wpisana na sztywno w docker-compose.yml, zamiast być odczytywana z .env, dlatego należy umieścić własne wartości w małym pliku nakładki. Nazwij go 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 ładuje docker-compose.override.yml automatycznie tylko wtedy, gdy uruchamia się go bez flagi -f, a każde polecenie w przewodniku Zitadel przekazuje -f, co wyłącza to zachowanie. Zamiast powtarzać rosnącą listę flag, przypnij listę plików w .env:
COMPOSE_FILE=docker-compose.yml:docker-compose.mode-letsencrypt.yml:docker-compose.local.ymlTeraz uruchom usługę:
docker compose pull
docker compose up -d --wait--wait wstrzymuje wykonanie polecenia do momentu przejścia testów poprawności (healthchecks). Jeśli kontener API ich nie przejdzie, Compose zatrzyma się z błędem dependency failed to start: container zitadel-zitadel-api-1 is unhealthy, a docker compose logs zitadel-api zawiera przyczynę. Kontener jest nazywany zgodnie z nazwą projektu, a dostarczony plik compose ustawia ją za pomocą klucza najwyższego poziomu name: zitadel, więc nazwa katalogu nie ma znaczenia. Przy pierwszym uruchomieniu przyczyną jest zazwyczaj długość klucza głównego (masterkey) lub DSN bazy danych.
Zaloguj się pod adresem https://auth.example.com/ui/console, zmień hasło, a następnie włącz drugi składnik uwierzytelniania (2FA) dla tego konta, zanim utworzysz cokolwiek innego. Każda wartość ZITADEL_FIRSTINSTANCE_* ma zastosowanie tylko podczas tworzenia pierwszej instancji. Gdy instancja już istnieje, edycja tych wartości nie przynosi żadnego efektu.
Dlaczego resetowanie hasła nie działa bez skonfigurowanego SMTP
Dostawca tożsamości, który nie może wysyłać wiadomości e-mail, jest niesprawny w sposób, który może pozostać niezauważony przez tygodnie. Zitadel wysyła wiadomości e-mail w celu zapraszania użytkowników, weryfikacji adresów, przesyłania linków do resetowania hasła, kodów jednorazowych oraz powiadomień o przejęciu domeny. Bez skonfigurowanego dostawcy SMTP konsola nadal zgłasza wykonanie akcji, a wiadomość trafia do kolejki powiadomień, nie mając miejsca docelowego. W wersji v4.20.0 powiadomienia domyślnie korzystają z trybu legacy (LegacyEnabled: true), który ignoruje ustawienia MaxAttempts: 3 oraz MaxTtl: 5m dla procesów równoległych. Wartości te nie opisują domyślnego zachowania ponawiania prób powiadomień. Użytkownik oczekujący na link nie otrzymuje żadnej informacji zwrotnej.
Konfigurację należy przeprowadzić w konsoli, w ustawieniach instancji pod adresem https://auth.example.com/ui/console/settings. Formularz dostawcy SMTP wymaga podania adresu e-mail nadawcy, nazwy nadawcy, hosta i portu, użytkownika, hasła SMTP oraz przełącznika TLS. Przed zapisaniem zmian należy użyć przycisku testowego w formularzu, ponieważ wysyła on rzeczywistą wiadomość: albo dotrze ona do odbiorcy, albo nie. Należy aktywować dostawcę, aby Zitadel mógł go używać do wysyłki poczty.
Istnieje odpowiedni zestaw zmiennych środowiskowych, ZITADEL_DEFAULTINSTANCE_SMTPCONFIGURATION_SMTP_HOST i powiązane z nimi. Mają one zastosowanie w momencie tworzenia instancji. W przypadku działającego stosu nie wywierają one żadnego wpływu, dlatego konsola jest właściwym miejscem dla istniejącej instancji.
Należy zwrócić uwagę na dwie kwestie dotyczące dostarczania poczty z VPS, ponieważ to właśnie tam najczęściej występują problemy. Przed wyborem przekaźnika (relay) należy sprawdzić politykę wychodzącego ruchu SMTP u dostawcy: DigitalOcean domyślnie blokuje porty 25, 465 oraz 587 na instancjach Droplet, więc port 587 nie jest uniwersalnym rozwiązaniem. Należy użyć uwierzytelnionego przekaźnika na porcie dozwolonym przez dostawcę. Ponadto należy opublikować rekordy SPF (sender policy framework) oraz DKIM (domainkeys identified mail) dla domeny nadawczej, w przeciwnym razie link do resetowania hasła trafi do spamu, co z perspektywy użytkownika wygląda dokładnie tak, jakby wiadomość nigdy nie została wysłana.
W wersji v4.20.0 wychodzące połączenia SMTP TLS odrzucają łańcuchy certyfikatów wykorzystujące skompromitowane urzędy certyfikacji pośredniej eMudhra. W przypadku korzystania z takiego przekaźnika wymagana jest wymiana certyfikatu.
Należy przeprowadzić test przed zaproszeniem jakichkolwiek użytkowników. Należy utworzyć tymczasowe konto, zażądać resetu hasła i sprawdzić, czy wiadomość dotarła. Jeśli nie, docker compose logs -f zitadel-api wskaże przyczynę błędu SMTP. Hasło SMTP jest przechowywane w bazie danych w postaci zaszyfrowanej, co stanowi kolejny element chroniony przez masterkey.
Oddzielne tworzenie kopii zapasowych Postgres i masterkey
Wszystkie dane Zitadel znajdują się w PostgreSQL. Kluczem do ich odszyfrowania jest masterkey. Należy tworzyć kopie zapasowe tych elementów w dwóch różnych lokalizacjach.
Najpierw zrzut bazy danych:
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 to format niestandardowy, który kompresuje dane podczas zapisu i który pg_restore potrafi odczytywać selektywnie. exec -T pomija terminal, co jest istotne, ponieważ proces ten jest uruchamiany przez cron bez przypisanego terminala.
Następnie należy przesłać ten katalog poza serwer za pomocą restic, który szyfruje i deduplikuje dane:
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 uruchamia się tylko raz, pierwszego dnia. Umieść zrzut oraz dwa ostatnie polecenia w /usr/local/bin/zitadel-backup.sh i uruchamiaj je co noc:
0 3 * * * /usr/local/bin/zitadel-backup.shTwórz kopie zapasowe .env oraz wszystkich używanych plików compose w git. Wyjątkiem od tej reguły jest masterkey. Powinien on znajdować się w menedżerze haseł oraz w drugiej lokalizacji, która nie jest tym samym repozytorium restic, ponieważ archiwum przechowujące bazę danych wraz z kluczem deszyfrującym przestaje być kopią zapasową zaszyfrowanego systemu.
Kopia zapasowa, której nie przywrócono, jest tylko przypuszczeniem. Przywróć dane do tymczasowej bazy danych na tym samym serwerze i sprawdź je:
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_testLista tabel w schemacie eventstore oznacza, że zrzut jest poprawny. Błąd informujący o braku schematu oznacza, że kopia jest nieprawidłowa, a fakt ten został wykryty w dniu, w którym nie wiąże się to z żadnymi kosztami. Ogólny schemat tworzenia kopii zapasowych i aktualizacji stosu Compose ma tutaj niemal niezmienione zastosowanie, a przechowywanie masterkey poza tym samym archiwum jest jedynym elementem specyficznym dla Zitadel.
Aktualizacja Zitadel bez utraty instancji
Aktualizacja polega na zmianie wersji w .env, po której następują dwa polecenia:
docker compose pull
docker compose up -d --waitZrozum działanie drugiego polecenia przed uruchomieniem go w środowisku, z którego korzystają użytkownicy. Polecenie kontenera to start-from-init, które wykonuje fazy inicjalizacji i konfiguracji przed rozpoczęciem serwowania ruchu, a faza konfiguracji obejmuje migracje bazy danych. Zmiana wersji powoduje więc uruchomienie migracji schematu na działającej bazie danych w momencie startu kontenera, bez nadzoru, podczas gdy --wait oczekuje na wynik testu stanu (healthcheck). To właśnie powód, dla którego powyższy test przywracania danych nie jest opcjonalny.
Wykonaj świeży zrzut bazy danych bezpośrednio przed aktualizacją. Zrzut z poprzedniego dnia jest niewystarczający.
W przypadku v4.20.3, trwające logowania przez zewnętrznych dostawców tożsamości muszą zostać zrestartowane, a nieodebrane kody autoryzacyjne Login V1 zostaną jednorazowo odrzucone. Niestandardowe interfejsy logowania wymagają uprawnienia session.link do poprawnego zakończenia żądań OIDC lub SAML; nadaj je użytkownikowi usługi IAM_LOGIN_CLIENT przed aktualizacją. Dostarczony użytkownik usługi Login V2 posiada już tę rolę. Sprawdzanie haseł przez Session API wymusza teraz politykę logowania organizacji użytkownika, więc organizacje, które wyłączyły logowanie nazwą użytkownika/hasłem, muszą kierować użytkowników do ich dostawcy tożsamości.
Nie pomijaj głównych wersji (major versions). Przed przejściem z v3 na v4, najpierw zaktualizuj do v3.4.1 lub nowszej. Wersja v4 czyni klucze internetowe OIDC obowiązkowymi i usuwa starszą ścieżkę podpisywania. Jeśli instancja v3 nigdy nie miała włączonych kluczy internetowych, tokeny podpisane starymi kluczami nie będą weryfikowalne po aktualizacji. Biuletyn techniczny Zitadel A-10017 informuje, że istniejące tokeny dostępu JWT oraz tokeny ID mogą stać się natychmiast nieważne, co zmusi użytkowników do ponownego zalogowania. Rozwiązaniem jest przejście przez v3.4.1 lub nowszą i odczekanie, aż tokeny i sesje podpisane starym sposobem wygasną przed aktualizacją, lub zaakceptowanie planowanego okna ponownego logowania. Jeśli używasz już v3.4.1 lub nowszej i odczekałeś od momentu włączenia kluczy internetowych, biuletyn wskazuje, że żadne dodatkowe działania nie są wymagane.
Monitoruj fazę konfiguracji za pomocą docker compose logs -f zitadel-api. Migracje na dużym eventstore trwają minuty, a Traefik nie przekieruje ruchu do API, dopóki test stanu nie przejdzie pomyślnie, więc serwis będzie w tym czasie niedostępny. Zaplanuj to, zamiast odkrywać to w trakcie.
Wycofanie zmian (rollback) nie polega na przywróceniu starego tagu. Po wykonaniu migracji, starsza binarka nie rozumie napotkanego schematu, więc wycofanie oznacza przywrócenie zrzutu bazy danych. Gdy instancja obsługuje rzeczywistych użytkowników, przejdź na docker-compose.prodlike.yml, czyli nakładkę, która uruchamia inicjalizację i konfigurację jako kroki oddzielone od startu, dzięki czemu migracja jest procesem wyzwalanym i monitorowanym, a nie efektem ubocznym restartu kontenera.
Co wskazać w nowym dostawcy tożsamości
W konsoli należy utworzyć projekt, a następnie aplikację w jego obrębie. Dla nowoczesnych rozwiązań należy wybrać OIDC, a Zitadel wygeneruje identyfikator klienta (client ID), sekret klienta (client secret) oraz dokument discovery pod adresem https://auth.example.com/.well-known/openid-configuration. Większość oprogramowania self-hosted obsługującego logowanie jednokrotne (SSO) wymaga właśnie tych danych.
Wiele aplikacji nie obsługuje tego standardu lub oferuje go tylko w płatnych wersjach. W pierwszym przypadku oauth2-proxy przed aplikacją pozwala zabezpieczyć dowolną usługę HTTP za pomocą Zitadel. W drugim przypadku warto przeczytać podatek od SSO w aplikacjach self-hosted przed zaplanowaniem migracji opartej na funkcji, za którą nie wniesiono opłaty.
FAQ
Ile pamięci RAM i procesora wymaga samodzielnie hostowany Zitadel?
Przewodnik produkcyjny Zitadel podaje, że sam Zitadel wymaga około 0.5 GB pamięci RAM i może działać na mniej niż jednym rdzeniu procesora, przy czym zaleca się pozostawienie 4 rdzeni do obsługi haszowania haseł. PostgreSQL jest rozliczany oddzielnie, w przybliżeniu jeden rdzeń na 100 żądań na sekundę oraz 4 GB pamięci RAM na rdzeń. Wyższe wartości w przewodniku dotyczą pojedynczego węzła w trzywęzłowym klastrze wysokiej dostępności: 4 rdzeni i 16 GB na każdy, lub około 4 rdzeni i 8 GB bez zbierania logów i metryk. Szybki start z użyciem Compose wymaga co najmniej 2 GB, co wystarcza do przetestowania rozwiązania, ale pozostawia niewiele miejsca dla bazy danych, której będą potrzebować inne usługi systemowe.
Co się stanie, jeśli utracę klucz główny (masterkey) Zitadel?
Wszystkie dane zaszyfrowane tym kluczem pozostaną zaszyfrowane. Poświadczenia dostawców tożsamości, hasło SMTP oraz ziarna haseł jednorazowych (OTP) nie będą możliwe do odszyfrowania, a klucza nie można zmienić po fakcie. Sam zrzut bazy danych nie pozwala na przywrócenie działającej instancji, ponieważ zrzut zawiera tekst zaszyfrowany, a nie klucz. Klucz główny należy przechowywać w menedżerze haseł, w miejscu oddzielonym od kopii zapasowej zawierającej zrzut bazy. Jeśli oba elementy zostaną utracone, jedyną drogą jest zbudowanie instancji od podstaw.
Dlaczego e-maile z resetem hasła Zitadel nigdy nie docierają?
Przyczyną jest brak konfiguracji dostawcy SMTP lub niezdolność skonfigurowanego dostawcy do dostarczenia wiadomości. Zitadel w wersji 4.20.0 domyślnie używa starszego mechanizmu przetwarzania powiadomień, więc ustawienia trzech prób i pięciu minut dla procesów równoległych są ignorowane. Należy skonfigurować dostawcę SMTP w ustawieniach instancji i użyć przycisku testowego w formularzu, który wysyła rzeczywistą wiadomość. Należy aktywować dostawcę, użyć uwierzytelnionego przekaźnika (relay) na porcie dozwolonym przez dostawcę VPS oraz opublikować rekordy SPF i DKIM dla domeny nadawcy, aby poczta nie była filtrowana jako spam.
Czy mogę zmienić domenę zewnętrzną Zitadel po instalacji?
Tak, ale nie poprzez edycję samego .env. Należy zmienić ZITADEL_EXTERNALDOMAIN, ZITADEL_EXTERNALPORT oraz ZITADEL_EXTERNALSECURE, a następnie pozwolić Zitadel na ponowne uruchomienie fazy konfiguracji, aby uwzględniła zmiany. Zarejestrowane już aplikacje zachowują swoje stare identyfikatory URI przekierowań i muszą zostać zaktualizowane ręcznie, a każde żądanie, którego nagłówek Host nie pasuje do domeny znanej Zitadel, otrzyma odpowiedź Instance not found. Wybór docelowej nazwy przed pierwszym uruchomieniem pozwala uniknąć tych czynności.