This guide installs ZITADEL on a Linux host. ZITADEL requires a database backend (PostgreSQL recommended) and supports multiple deployment options.
ZITADEL follows an event-sourced architecture and requires a PostgreSQL database as its primary data store. The system stores all identity events in the database, which enables audit trails and historical state reconstruction.
Create a PostgreSQL database and user for ZITADEL:
# Connect to PostgreSQL as superuser
sudo -u postgres psql
# Create database and user
CREATE DATABASE zitadel;
CREATE USER zitadel WITH PASSWORD 'your_secure_password';
GRANT ALL PRIVILEGES ON DATABASE zitadel TO zitadel;
\q
# Update system packages
sudo apt update && sudo apt upgrade -y
# Install prerequisites
sudo apt install -y curl wget gnupg ca-certificates
# Create dedicated user for ZITADEL
sudo useradd -r -s /bin/false zitadel
Download the latest release from GitHub:
# Define version (use latest stable)
VERSION="4.10.1"
# Download binary
wget https://github.com/zitadel/zitadel/releases/download/v${VERSION}/zitadel_${VERSION}_linux_amd64.tar.gz
# Extract
tar -xzf zitadel_${VERSION}_linux_amd64.tar.gz
# Move binary to system path
sudo mv zitadel /usr/local/bin/
sudo chown zitadel:zitadel /usr/local/bin/zitadel
sudo chmod +x /usr/local/bin/zitadel
ZITADEL provides DEB and RPM packages for easier management:
# For Debian/Ubuntu systems
curl -sSfL https://raw.githubusercontent.com/zitadel/zitadel/main/install.sh | sh -s -- -b /tmp
sudo install -m 755 /tmp/zitadel /usr/local/bin/zitadel
# For RHEL/CentOS/Fedora systems
sudo dnf config-manager --add-repo https://github.com/zitadel/zitadel/raw/main/zitadel.repo
sudo dnf install zitadel
sudo mkdir -p /etc/zitadel
sudo chown zitadel:zitadel /etc/zitadel
Create /etc/zitadel/config.yaml:
# Database configuration
database:
postgres:
host: localhost
port: 5432
database: zitadel
user: zitadel
password: your_secure_password
ssl:
mode: disable # Use 'require' for production with SSL
# Server configuration
external:
issuer: https://your-domain.com # Replace with your domain
cors:
allowed_origins: ["https://your-domain.com"]
# Master key for encryption
keys:
crypto:
encryption_key: "YOUR_MASTER_KEY_HERE" # Generate a secure random key
# Feature flags
features:
unique_org_id: true
Initialize the database and create the first organization:
# Initialize database
sudo -u zitadel zitadel database setup \
--config /etc/zitadel/config.yaml \
--masterkey "YOUR_MASTER_KEY_HERE" \
--organization.name "Main Organization" \
--human.username "admin" \
--human.email "admin@your-domain.com" \
--human.password "SecurePassword123!"
Create /etc/systemd/system/zitadel.service:
[Unit]
Description=ZITADEL Identity Management
After=network.target postgresql.service
Wants=postgresql.service
[Service]
Type=simple
User=zitadel
Group=zitadel
ExecStart=/usr/local/bin/zitadel start --config /etc/zitadel/config.yaml
Restart=always
RestartSec=10
# Security settings
NoNewPrivileges=true
PrivateTmp=true
ProtectSystem=strict
ReadWritePaths=/etc/zitadel
[Install]
WantedBy=multi-user.target
Enable and start the service:
sudo systemctl daemon-reload
sudo systemctl enable zitadel
sudo systemctl start zitadel
sudo systemctl status zitadel
Check if ZITADEL is running:
# Check service status
sudo systemctl status zitadel
# Check logs
sudo journalctl -u zitadel -f
# Verify connectivity (replace with your domain)
curl -I https://your-domain.com
Access the ZITADEL console at https://your-domain.com/ui/console and log in with the admin credentials created during initialization.
Common issues and solutions:
Need professional assistance with your identity management infrastructure? Our team provides:
Get in touch: office@linux-server-admin.com | Contact Page