zitadel/docs/docs/self-hosting/manage/production.md

title
Production Checklist

As soon as you successfully deployed ZITADEL as a proof of concept using one of our deployment guides, you are ready to configure ZITADEL for production usage.

High Availability

We recommend running ZITADEL highly available using an orchestrator that schedules ZITADEL on multiple servers, like [Kubernetes]/docs/self-hosting/deploy/kubernetes). For keeping startup times fast when scaling ZITADEL, you should also consider using separate jobs with zitadel init and zitadel setup, so your workload containers just have to execute zitadel start.

Configuration

Read on the configure page about the available options you have to configure ZITADEL.

Networking

• To make ZITADEL available at the domain of your choice, you need to configure the ExternalDomain property.
• To enable and restrict access to HTTPS, head over to the description of your TLS options.
• If you want to front ZITADEL with a reverse proxy, web application firewall or content delivery network, make sure to support HTTP/2.
• You can also refer to some example reverse proxy configurations.
• The ZITADEL Console web GUI uses many gRPC-Web stubs. This results in a fairly big JavaScript bundle. You might want to compress it using Gzip or Brotli.
• Serving and caching the assets using a content delivery network could improve network latencies and shield your ZITADEL runtime.

Monitoring

By default, metrics are exposed at /debug/metrics in OpenTelemetry (otel) format.

Also, you can enable tracing in the ZITADEL configuration.

Tracing:
  # Choose one in "otel", "google", "log" and "none"
  Type: google
  Fraction: 1
  MetricPrefix: zitadel

Database

Prefer CockroachDB

ZITADEL supports CockroachDB and PostgreSQL. We highly recommend using CockroachDB, as horizontal scaling is much easier than with PostgreSQL. Also, if you are concerned about multi-regional data locality, the way to go is with CockroachDB.

Configure ZITADEL

Depending on your environment, you maybe would want to tweak some settings about how ZITADEL interacts with the database in the database section of your ZITADEL configuration. Read more about your database configuration options.

Database:
  cockroach:
    Host: localhost
    Port: 26257
    Database: zitadel
    //highlight-start
    MaxOpenConns: 20
    MaxConnLifetime: 30m
    MaxConnIdleTime: 30m
    //highlight-end
    Options: ""

You also might want to configure how projections are computed. These are the default values:

Projections:
  RequeueEvery: 60s
  RetryFailedAfter: 1s
  MaxFailureCount: 5
  ConcurrentInstances: 1
  BulkLimit: 200
  MaxIterators: 1
  Customizations:
    projects:
      BulkLimit: 2000

Manage your Data

When designing your backup strategy, it is worth knowing that ZITADEL is event sourced. That means, ZITADEL itself is able to recompute its whole state from the records in the table eventstore.events. The timestamp of your last record in the events table defines up to which point in time ZITADEL can restore its state.

The ZITADEL binary itself is stateless, so there is no need for a special backup job.

Generally, for maintaining your database management system in production, please refer to the corresponding docs for CockroachDB or for PostgreSQL.

Data Initialization

• You can configure instance defaults in the DefaultInstance section. If you plan to eventually create multiple virtual instances, these defaults take effect. Also, these configurations apply to the first instance, that ZITADEL automatically creates for you. Especially the following properties are of special interest for your production setup.

DefaultInstance:
  OIDCSettings:
    AccessTokenLifetime: 12h
    IdTokenLifetime: 12h
    RefreshTokenIdleExpiration: 720h #30d
    RefreshTokenExpiration: 2160h #90d
  # this configuration sets the default email configuration
  SMTPConfiguration:
    # configuration of the host
    SMTP:
      #for example smtp.mailtrap.io:2525
      Host:
      User:
      Password:
    TLS:
    # if the host of the sender is different from ExternalDomain set DefaultInstance.DomainPolicy.SMTPSenderAddressMatchesInstanceDomain to false
    From:
    FromName:

• If you don't want to use the DefaultInstance configuration for the first instance that ZITADEL automatically creates for you during the setup phase, you can provide a FirstInstance YAML section using the --steps argument.
• Learn how to configure ZITADEL via the Console user interface.
• Probably, you also want to apply your custom branding, hook into certain events, customize texts or add metadata to your users.
• If you want to automatically create ZITADEL resources, you can use the ZITADEL Terraform Provider.