Zitadel

advanced

Cloud-native identity and access management.

Overview

Zitadel is a cloud-native identity and access management (IAM) platform developed by CAOS Ltd that provides comprehensive authentication, authorization, and user management capabilities. Built with modern microservices architecture in mind, Zitadel offers multi-tenancy support, extensive API coverage, and supports multiple authentication protocols including OpenID Connect, OAuth 2.0, SAML, and JWT tokens. Unlike traditional IAM solutions, Zitadel was designed from the ground up to be cloud-native, providing built-in audit logging, event sourcing, and horizontal scalability. This deployment pairs Zitadel with CockroachDB, a distributed SQL database that provides the resilient, scalable backend storage Zitadel requires for its event sourcing architecture. CockroachDB's strong consistency guarantees and automatic failover capabilities make it an ideal match for Zitadel's audit requirements and multi-tenant data isolation needs. The combination creates a robust IAM infrastructure that can handle enterprise-scale authentication workloads while maintaining data integrity and compliance requirements. This stack is particularly valuable for organizations implementing zero-trust security models, SaaS platforms requiring multi-tenant user management, and development teams building modern applications that need enterprise-grade identity services. The Zitadel-CockroachDB combination excels in scenarios where audit trails are critical, user data must be strictly isolated between tenants, and the identity system needs to scale horizontally across multiple regions or availability zones.

Key Features

Multi-tenant identity management with strict data isolation between organizations
Event sourcing architecture with complete audit trails stored in CockroachDB
Built-in support for OIDC, OAuth 2.0, SAML 2.0, and JWT token-based authentication
CockroachDB's distributed SQL capabilities enabling horizontal scaling across multiple nodes
Comprehensive user lifecycle management including registration, verification, and password policies
Project-based application organization with granular permission controls
Real-time user session management with configurable timeout and security policies
CockroachDB's automatic data replication and consistency guarantees for identity data

Common Use Cases

1Multi-tenant SaaS applications requiring isolated user management per customer organization
2Enterprise single sign-on implementation replacing legacy Active Directory dependencies
3Microservices architecture requiring centralized authentication and authorization
4Compliance-heavy industries needing complete audit trails of user access and permissions
5API-first applications requiring OAuth 2.0 and JWT token management at scale
6Development teams building modern web applications with social login integration
7Organizations implementing zero-trust security models with identity-based access controls

Prerequisites

Docker Engine 20.10+ and Docker Compose V2 for container orchestration support
Minimum 4GB RAM available (2GB for Zitadel, 2GB for CockroachDB operations)
Port 8080 available for Zitadel web console and API access
OpenSSL installed for generating the required ZITADEL_MASTERKEY encryption key
Basic understanding of OAuth 2.0/OIDC flows for application integration
10GB minimum disk space for CockroachDB data persistence and growth

For development & testing. Review security settings, change default credentials, and test thoroughly before production use. See Terms

docker-compose.yml

1services: 
2  zitadel: 
3    image: ghcr.io/zitadel/zitadel:latest
4    container_name: zitadel
5    restart: unless-stopped
6    command: start-from-init --masterkeyFromEnv --tlsMode disabled
7    environment: 
8      ZITADEL_MASTERKEY: ${MASTER_KEY}
9      ZITADEL_DATABASE_COCKROACH_HOST: cockroachdb
10      ZITADEL_EXTERNALSECURE: "false"
11      ZITADEL_EXTERNALPORT: 8080
12      ZITADEL_EXTERNALDOMAIN: localhost
13    ports: 
14      - "8080:8080"
15    depends_on: 
16      - cockroachdb
17
18  cockroachdb: 
19    image: cockroachdb/cockroach:latest
20    container_name: zitadel-db
21    command: start-single-node --insecure
22    volumes: 
23      - zitadel_db:/cockroach/cockroach-data
24
25volumes: 
26  zitadel_db:

.env Template

.env

1MASTER_KEY=generate-32-char-key-here

Usage Notes

1Docs: https://zitadel.com/docs
2Console at http://localhost:8080 after initialization
3Generate MASTER_KEY: openssl rand -base64 32 | head -c 32
4Initial admin credentials shown in container logs
5Create projects, then applications within projects
6Supports OIDC, SAML, JWT, and API key authentication

Individual Services(2 services)

Copy individual services to mix and match with your existing compose files.

zitadel

zitadel:
  image: ghcr.io/zitadel/zitadel:latest
  container_name: zitadel
  restart: unless-stopped
  command: start-from-init --masterkeyFromEnv --tlsMode disabled
  environment:
    ZITADEL_MASTERKEY: ${MASTER_KEY}
    ZITADEL_DATABASE_COCKROACH_HOST: cockroachdb
    ZITADEL_EXTERNALSECURE: "false"
    ZITADEL_EXTERNALPORT: 8080
    ZITADEL_EXTERNALDOMAIN: localhost
  ports:
    - "8080:8080"
  depends_on:
    - cockroachdb

cockroachdb

cockroachdb:
  image: cockroachdb/cockroach:latest
  container_name: zitadel-db
  command: start-single-node --insecure
  volumes:
    - zitadel_db:/cockroach/cockroach-data

Quick Start

terminal

1# 1. Create the compose file
2cat > docker-compose.yml << 'EOF'
3services:
4  zitadel:
5    image: ghcr.io/zitadel/zitadel:latest
6    container_name: zitadel
7    restart: unless-stopped
8    command: start-from-init --masterkeyFromEnv --tlsMode disabled
9    environment:
10      ZITADEL_MASTERKEY: ${MASTER_KEY}
11      ZITADEL_DATABASE_COCKROACH_HOST: cockroachdb
12      ZITADEL_EXTERNALSECURE: "false"
13      ZITADEL_EXTERNALPORT: 8080
14      ZITADEL_EXTERNALDOMAIN: localhost
15    ports:
16      - "8080:8080"
17    depends_on:
18      - cockroachdb
19
20  cockroachdb:
21    image: cockroachdb/cockroach:latest
22    container_name: zitadel-db
23    command: start-single-node --insecure
24    volumes:
25      - zitadel_db:/cockroach/cockroach-data
26
27volumes:
28  zitadel_db:
29EOF
30
31# 2. Create the .env file
32cat > .env << 'EOF'
33MASTER_KEY=generate-32-char-key-here
34EOF
35
36# 3. Start the services
37docker compose up -d
38
39# 4. View logs
40docker compose logs -f

One-Liner

Run this command to download and set up the recipe in one step:

terminal

1curl -fsSL https://docker.recipes/api/recipes/zitadel/run | bash

Troubleshooting

Zitadel fails to start with 'masterkey invalid': Generate a proper 32-character base64 key using 'openssl rand -base64 32 | head -c 32' and set in MASTER_KEY environment variable
Cannot access console at localhost:8080: Check that ZITADEL_EXTERNALDOMAIN matches your access hostname and ZITADEL_EXTERNALPORT is properly configured
Database connection errors on startup: Verify CockroachDB container is healthy and accessible - check logs with 'docker logs zitadel-db' for initialization issues
CockroachDB fails with 'insufficient disk space': Ensure at least 10GB free space and check volume mount permissions for the cockroach user
Initial admin credentials not visible: Check Zitadel container logs during first startup with 'docker logs zitadel' - credentials are only shown once during initialization
Application registration fails with domain errors: Verify ZITADEL_EXTERNALDOMAIN and ZITADEL_EXTERNALSECURE settings match your actual access method and SSL configuration

Community Notes

Loading notes...

Download Recipe Kit

Get all files in a ready-to-deploy package

Includes docker-compose.yml, .env template, README, and license

Components

zitadelcockroachdb

Related Recipes

Ad Space

Shortcuts: C CopyF FavoriteD Download