Skip to content
Klutch.sh Docs

Deploying a Zitadel App

Introduction

Zitadel is an open-source identity and access management platform. This guide shows how to containerize Zitadel with a Dockerfile, connect it to PostgreSQL, persist data, and deploy it to Klutch.sh over HTTP.

Prerequisites

  • GitHub repository containing your Dockerfile.
  • PostgreSQL database (managed or deployed separately).
  • Klutch.sh project ready in klutch.sh/app.

Project structure

.
└── Dockerfile

Sample Dockerfile

FROM ghcr.io/zitadel/zitadel:latest


# Default Zitadel port
ENV PORT=8080
EXPOSE 8080

Required environment variables

  • ZITADEL_DATABASE_POSTGRES_HOST
  • ZITADEL_DATABASE_POSTGRES_PORT – e.g., 5432
  • ZITADEL_DATABASE_POSTGRES_DATABASE
  • ZITADEL_DATABASE_POSTGRES_USER
  • ZITADEL_DATABASE_POSTGRES_PASSWORD
  • PORT=8080
  • ZITADEL_EXTERNALSECURE=true – rely on HTTPS termination at the edge

Optional environment variables

  • ZITADEL_LOG_LEVEL=info
  • ZITADEL_TELEMETRY_ENABLED=false
  • ZITADEL_DEFAULTINSTANCE_NAME – branding
  • ZITADEL_DEFAULTINSTANCE_DOMAIN – e.g., example-app.klutch.sh

Persistence

All state is stored in PostgreSQL. If you log locally, attach a volume:

  • Mount path: /zitadel/logs
  • Size: based on retention needs

Networking

  • Protocol: HTTP
  • Internal port: 8080
  • Users reach https://example-app.klutch.sh while Klutch.sh routes to port 8080 inside the container.
Terminal window
curl -I http://localhost:8080/debug/health

Deployment on Klutch.sh

  1. Push your Dockerfile to GitHub.
  2. In klutch.sh/app, create a new app and select GitHub as the source.
  3. Klutch.sh automatically detects the Dockerfile in the repository root.
  4. Select HTTP traffic and set the internal port to 8080.
  5. Add environment variables for PostgreSQL connectivity and Zitadel settings (host, port, db, user, password, and any branding domains). Mark secrets as sensitive.
  6. Optionally attach a volume at /zitadel/logs if you need local log retention.
  7. Deploy. After the app starts, finish the Zitadel setup, create your admin account, and configure projects and clients.

Verification

  • Health:

    Terminal window
    curl https://example-app.klutch.sh/debug/health

  • UI: open https://example-app.klutch.sh/ui/console and sign in.

Next steps

  • Configure HTTPS at the edge and set ZITADEL_DEFAULTINSTANCE_DOMAIN.
  • Enable backups for PostgreSQL.
  • Set up OAuth/OIDC clients, service accounts, and policies as needed.