Lyamc: Created this first-draft page in order to document the service.

2026-03-29T06:29:37Z

Created this first-draft page in order to document the service.

New page

'''[https://zitadel.com/ Zitadel]''' is an open-source identity and access management platform built for the cloud-native era. It provides authentication, authorization, and user management with support for OIDC, SAML, MFA, and more.

== Setup (Native / Containerless) ==
The following configuration provides a complete, declarative setup for Zitadel with:

* [[PostgreSQL]] (no Docker)
* [[Nginx]] reverse proxy using existing ACME certificates
* Declarative creation

== Configuration ==
Modify and save the configuration as <code>/etc/nixos/services/zitadel.n</code><code>ix</code>

nix
{ config, pkgs, lib, ... }:

let
<nowiki> </nowiki> # Root domain, using Wildcard Certificate as per <nowiki>https://wiki.nixos.org/wiki/ACME</nowiki> CloudFlare section
<nowiki> </nowiki> # If using per-domain certificates, change to the appropriate subdomain.
<nowiki> </nowiki> rootDomain = "example.com";

<nowiki> </nowiki> # Domain where Zitadel will be available.
<nowiki> </nowiki> # Change to rootDomain if using per-domain ACME certificates
<nowiki> </nowiki> zitadelDomain = "auth.${rootDomain}";

<nowiki> </nowiki> # Strong password for the dedicated PostgreSQL user
<nowiki> </nowiki> dbPassword = "make-sure-this-is-secure-and-long";

<nowiki> </nowiki> # Initial admin password for the Zitadel console
<nowiki> </nowiki> # Change this immediately after first login!
<nowiki> </nowiki> adminPassword = "change-this-immediately-to-a-strong-password";

<nowiki> </nowiki> # Email address for the initial admin user
<nowiki> </nowiki> initialAdminEmail = "admin@${rootDomain}";

<nowiki> </nowiki> # Internal port Zitadel listens on (chosen to avoid conflict with other services on port 80)
<nowiki> </nowiki> internalPort = 2080;

<nowiki> </nowiki> # External port when using TLS Enabled or for reverse proxy with external TLS mode
<nowiki> </nowiki> # Currently only works with 443, see <nowiki>https://github.com/zitadel/zitadel/issues/11380</nowiki>
<nowiki> </nowiki> externalPort = 443;

<nowiki> </nowiki> # false = HTTP, true = HTTPS
<nowiki> </nowiki> externalSecure = true;

<nowiki> </nowiki> # Zitadel TLS Mode (disabled, enabled, external)
<nowiki> </nowiki> tlsMode = "disabled";

in
{
<nowiki> </nowiki> # === PostgreSQL ===
<nowiki> </nowiki> services.postgresql = {
<nowiki> </nowiki> enable = true;
<nowiki> </nowiki> package = pkgs.postgresql_17;

<nowiki> </nowiki> ensureDatabases = [ "zitadel" ];

<nowiki> </nowiki> # Enable TCP/IP for localhost connections
<nowiki> </nowiki> enableTCPIP = true;

<nowiki> </nowiki> # Authentication rules
<nowiki> </nowiki> authentication = pkgs.lib.mkOverride 10 <nowiki>''</nowiki>
<nowiki> </nowiki> # Local Unix socket connections use peer authentication
<nowiki> </nowiki> local all all peer

<nowiki> </nowiki> # TCP localhost: allow zitadel user to connect to any database
<nowiki> </nowiki> host all zitadel 127.0.0.1/32 trust
<nowiki> </nowiki> host all zitadel ::1/128 trust
<nowiki> </nowiki> <nowiki>''</nowiki>;

<nowiki> </nowiki> # Initial database setup
<nowiki> </nowiki> initialScript = pkgs.writeText "zitadel-init.sql" <nowiki>''</nowiki>
<nowiki> </nowiki> CREATE ROLE zitadel WITH LOGIN PASSWORD '${dbPassword}' CREATEDB CREATEROLE;
<nowiki> </nowiki> GRANT ALL PRIVILEGES ON DATABASE zitadel TO zitadel;
<nowiki> </nowiki> <nowiki>''</nowiki>;

<nowiki> </nowiki> settings = {
<nowiki> </nowiki> max_connections = 100;
<nowiki> </nowiki> shared_buffers = "256MB";
<nowiki> </nowiki> };
<nowiki> </nowiki> };

<nowiki> </nowiki> # Ensure the zitadel role always has CREATEROLE for migrations
<nowiki> </nowiki> systemd.services.zitadel-postgres-setup = {
<nowiki> </nowiki> description = "Ensure Zitadel PostgreSQL user has required privileges";
<nowiki> </nowiki> wantedBy = [ "multi-user.target" ];
<nowiki> </nowiki> after = [ "postgresql.service" ];
<nowiki> </nowiki> requires = [ "postgresql.service" ];

<nowiki> </nowiki> serviceConfig = {
<nowiki> </nowiki> Type = "oneshot";
<nowiki> </nowiki> RemainAfterExit = true;
<nowiki> </nowiki> User = "postgres";
<nowiki> </nowiki> };

<nowiki> </nowiki> script = <nowiki>''</nowiki>
<nowiki> </nowiki> ${config.services.postgresql.package}/bin/psql -d postgres <<'EOF'
<nowiki> </nowiki> DO $$
<nowiki> </nowiki> BEGIN
<nowiki> </nowiki> IF NOT EXISTS (SELECT FROM pg_roles WHERE rolname = 'zitadel') THEN
<nowiki> </nowiki> CREATE ROLE zitadel WITH LOGIN PASSWORD '${dbPassword}' CREATEDB CREATEROLE;
<nowiki> </nowiki> ELSE
<nowiki> </nowiki> ALTER ROLE zitadel WITH PASSWORD '${dbPassword}' CREATEDB CREATEROLE;
<nowiki> </nowiki> END IF;
<nowiki> </nowiki> END
<nowiki> </nowiki> $$;

<nowiki> </nowiki> GRANT ALL PRIVILEGES ON DATABASE zitadel TO zitadel;
<nowiki> </nowiki> EOF
<nowiki> </nowiki> <nowiki>''</nowiki>;
<nowiki> </nowiki> };

<nowiki> </nowiki> # === Zitadel ===
<nowiki> </nowiki> services.zitadel = {
<nowiki> </nowiki> enable = true;

<nowiki> </nowiki> masterKeyFile = "/var/lib/zitadel/master.key";

<nowiki> </nowiki> tlsMode = tlsMode;
<nowiki> </nowiki> settings = {
<nowiki> </nowiki> Port = httpPort;
<nowiki> </nowiki> ExternalPort = httpsPort;
<nowiki> </nowiki> ExternalDomain = zitadelDomain;
<nowiki> </nowiki> ExternalSecure = externalSecure;

<nowiki> </nowiki> Database = {
<nowiki> </nowiki> postgres = {
<nowiki> </nowiki> Host = "127.0.0.1";
<nowiki> </nowiki> Port = 5432;
<nowiki> </nowiki> Database = "zitadel";

<nowiki> </nowiki> User = {
<nowiki> </nowiki> Username = "zitadel";
<nowiki> </nowiki> Password = dbPassword;
<nowiki> </nowiki> SSL = { Mode = "disable"; };
<nowiki> </nowiki> };

<nowiki> </nowiki> Admin = {
<nowiki> </nowiki> Username = "zitadel";
<nowiki> </nowiki> Password = dbPassword;
<nowiki> </nowiki> SSL = { Mode = "disable"; };
<nowiki> </nowiki> };
<nowiki> </nowiki> };
<nowiki> </nowiki> };
<nowiki> </nowiki> };

<nowiki> </nowiki> # Declarative first instance and admin user
<nowiki> </nowiki> steps = {
<nowiki> </nowiki> FirstInstance = {
<nowiki> </nowiki> InstanceName = "Zitadel";
<nowiki> </nowiki> Org = {
<nowiki> </nowiki> Human = {
<nowiki> </nowiki> UserName = "admin";
<nowiki> </nowiki> FirstName = "Admin";
<nowiki> </nowiki> LastName = "User";
<nowiki> </nowiki> DisplayName = "Administrator";
<nowiki> </nowiki> Password = adminPassword;
<nowiki> </nowiki> PasswordChangeRequired = false;
<nowiki> </nowiki> Email = {
<nowiki> </nowiki> Address = initialAdminEmail;
<nowiki> </nowiki> Verified = true;
<nowiki> </nowiki> };
<nowiki> </nowiki> };
<nowiki> </nowiki> };
<nowiki> </nowiki> };
<nowiki> </nowiki> };
<nowiki> </nowiki> };

<nowiki> </nowiki> # Generate persistent master key (only once)
<nowiki> </nowiki> system.activationScripts.zitadelMasterKey = lib.stringAfter [ "var" ] <nowiki>''</nowiki>
<nowiki> </nowiki> mkdir -p /var/lib/zitadel
<nowiki> </nowiki> if [ ! -f /var/lib/zitadel/master.key ]; then
<nowiki> </nowiki> ${pkgs.coreutils}/bin/tr -dc 'A-Za-z0-9' </dev/urandom | head -c 32 > /var/lib/zitadel/master.key
<nowiki> </nowiki> chmod 400 /var/lib/zitadel/master.key
<nowiki> </nowiki> chown zitadel:zitadel /var/lib/zitadel/master.key || true
<nowiki> </nowiki> chown zitadel:zitadel /var/lib/zitadel || true
<nowiki> </nowiki> fi
<nowiki> </nowiki> <nowiki>''</nowiki>;

<nowiki> </nowiki> # === Nginx reverse proxy (HTTPS only) example ===
<nowiki> </nowiki> services.nginx.enable = true;

<nowiki> </nowiki> services.nginx.virtualHosts."${zitadelDomain}" = {
<nowiki> </nowiki> forceSSL = true;
<nowiki> </nowiki> sslCertificate = "/var/lib/acme/${rootDomain}/fullchain.pem";
<nowiki> </nowiki> sslCertificateKey = "/var/lib/acme/${rootDomain}/key.pem";

<nowiki> </nowiki> http2 = true; # Enables HTTP/2 support

<nowiki> </nowiki> # Necessary for non-default HTTPS port
<nowiki> </nowiki> listen = [
<nowiki> </nowiki> { addr = "0.0.0.0"; port = externalPort; ssl = true; }
<nowiki> </nowiki> { addr = "[::]"; port = externalPort; ssl = true; }
<nowiki> </nowiki> ];

<nowiki> </nowiki> locations = {
<nowiki> </nowiki> # Zitadel Login V2 UI
<nowiki> </nowiki> "/ui/v2/login" = {
<nowiki> </nowiki> proxyPass = "<nowiki>http://127.0.0.1:${toString</nowiki> internalPort}";
<nowiki> </nowiki> extraConfig = <nowiki>''</nowiki>
<nowiki> </nowiki> proxy_set_header Host $host;
<nowiki> </nowiki> proxy_set_header X-Real-IP $remote_addr;
<nowiki> </nowiki> proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
<nowiki> </nowiki> proxy_set_header X-Forwarded-Proto $scheme;
<nowiki> </nowiki> <nowiki>''</nowiki>;
<nowiki> </nowiki> };

<nowiki> </nowiki> # gRPC for Console, API, etc.
<nowiki> </nowiki> "/" = {
<nowiki> </nowiki> extraConfig = <nowiki>''</nowiki>
<nowiki> </nowiki> grpc_pass grpc://127.0.0.1:${toString internalPort};
<nowiki> </nowiki> grpc_set_header Host $host;
<nowiki> </nowiki> grpc_set_header X-Forwarded-Proto $scheme;
<nowiki> </nowiki> <nowiki>''</nowiki>;
<nowiki> </nowiki> };
<nowiki> </nowiki> };
<nowiki> </nowiki> };
<nowiki> </nowiki> };

<nowiki> </nowiki> systemd.services.zitadel = {
<nowiki> </nowiki> after = [ "postgresql.service" "zitadel-postgres-setup.service" ];
<nowiki> </nowiki> requires = [ "postgresql.service" "zitadel-postgres-setup.service" ];
<nowiki> </nowiki> };
}
Add the module to your configuration.nix:

nix
imports = [ ./services/zitadel.nix ];
After a successful rebuild, Zitadel will be available at <nowiki>https://auth.example.com</nowiki> (replace with your domain).

== Usage ==
Log in with username '''admin''' and the adminPassword you set. '''Change the password''' in the Zitadel console.

For further usage, refer to the official Zitadel documentation.

== Verification ==
Check that services are running:

Bash<syntaxhighlight lang="bash">
systemctl status zitadel-postgres-setup
systemctl status postgresql
systemctl status zitadel
systemctl status nginx
sudo tail /var/logs/ngnix/error.log
</syntaxhighlight>

== Notes ==

* This setup uses trust authentication for the zitadel user on localhost for a single-machine deployment.
* The zitadel-postgres-setup service ensures the database user has the CREATEROLE attribute required by Zitadel's initialization.
* TLS termination happens at Nginx using existing ACME certificates

== See Also ==
[[ACME]]

[[Keycloak]]

[https://zitadel.com/ Zitadel Offical Homepage]

[https://github.com/zitadel/zitadel/issues Zitadel GitHub Issue Tracker]

Zitadel - Revision history

Lyamc: Created this first-draft page in order to document the service.