Skip to main content

MacOS

Install CockroachDB​

Download a cockroach binary as described in the CockroachDB docs. ZITADEL is tested against CockroachDB v22.2.2.

Run CockroachDB​

cockroach start-single-node --insecure --background --http-addr :9090 --listen-addr=localhost

Install ZITADEL​

Homebrew​

brew install zitadel/tap/zitadel

Download from GitHub​

Download the ZITADEL release according to your architecture from Github

Unpack the archive​

move to your download location and unpack the archive

#unpack and copy to /usr/local/bin
LATEST=$(curl -i https://github.com/zitadel/zitadel/releases/latest | grep location: | cut -d '/' -f 8 | tr -d '\r'); wget -qO-  https://github.com/zitadel/zitadel/releases/download/$LATEST/zitadel_Darwin_$(uname -m).tar.gz  | tar -xJ zitadel && sudo mv zitadel /usr/local/bin

Run ZITADEL​

ZITADEL_EXTERNALSECURE=false zitadel start-from-init --masterkey "MasterkeyNeedsToHave32Characters" --tlsMode disabled

Open your favorite internet browser and navigate to http://localhost:8080/ui/console. This is the default IAM admin users login:

  • username: zitadel-admin@zitadel.localhost
  • password: Password1!
info

In the above username, replace localhost with your configured external domain, if any. e.g. with zitadel-admin@zitadel.sso.my.domain.tld

VideoGuide​

Setup ZITADEL with a service account​

ZITADEL_EXTERNALSECURE=false ZITADEL_FIRSTINSTANCE_MACHINEKEYPATH=/tmp/zitadel-admin-sa.json ZITADEL_FIRSTINSTANCE_ORG_MACHINE_MACHINE_USERNAME=zitadel-admin-sa ZITADEL_FIRSTINSTANCE_ORG_MACHINE_MACHINE_NAME=Admin ZITADEL_FIRSTINSTANCE_ORG_MACHINE_MACHINEKEY_TYPE=1 zitadel start-from-init --masterkey "MasterkeyNeedsToHave32Characters" --tlsMode disabled

# then you can move your machine key
mv /tmp/zitadel-admin-sa.json $HOME/zitadel-admin-sa.json

This key can be used to provision resources with for example Terraform.

What's next​

For running a production grade ZITADEL instance in your environment, go on with the configure ZITADEL section.

caution

The ZITADEL management console requires end-to-end HTTP/2 support

Disclaimer​

This guide is for development / demonstration purpose only and does NOT reflect a production setup.

Things such as TLS termination and email verification will not be available unless you

  • Use an API gateway with valid certificates in front of the service
  • Configure an appropriate email server