zitadel/CONTRIBUTING.md
mffap dd53f70fd5
docs(contributing): Update contributing guide (#3729)
* docs(contributing): Update contributing guide

* update link for login interface texts

* move gfi to main section

* contributing docs

* typos, links

Co-authored-by: Florian Forster <florian@caos.ch>

* chore(console): contributing to console (#3891)

* fix: return absolute url for avatar in user sessions (#3724)

* fix: return absolute url for avatar in user sessions

* fix: refresh token unique constraint

* feat: system api requires authenticated requests (#3570)

* begin auth

* feat: system api requires authenticated requests

* fix tests

* feat: directly specify factors/idps on addCustomLoginPolicy and return on LoginPolicy responses (#3711)

* feat: directly specify factors on addCustomLoginPolicy and return on LoginPolicy responses

* fix proto

* update login policy

* feat: directly specify idp on addCustomLoginPolicy and return on LoginPolicy responses

* fix: tests

Co-authored-by: Max Peintner <max@caos.ch>
Co-authored-by: Fabi <38692350+hifabienne@users.noreply.github.com>

* fix: read key data for system api users from config (#3731)

* chore: make docs searchable (#3734)

* chore: make docs searchable

* Update netlify.toml

* fix: SMTP config in defaults (#3736)

* fix(command): create smtp provider cmds after domains

* chore(defaults): add smtp configuration

* fix(console): Idp settings, settings reset warn dialog, Accept-Language header interceptor, i18n (#3727)

* fix idp table, settings reset warn dialog, fix i18n interceptor, i18n

* fix label policy on org change

* fallback

* fix preview button styles

* footer, login-policy null check

* org create btn alignment

* show error with toast

* error toast

* fix(console): header image fallback (#3735)

fix: fallback icon in header

Co-authored-by: Livio Amstutz <livio.a@gmail.com>

* fix(login): checkbox, label, container styles (#3732)

fix: checkbox, label styles

* docs: add java sample project (#3738)

Co-authored-by: Fabi <38692350+hifabienne@users.noreply.github.com>

* fix: use issuer for jwt profile check on system api (#3741)

* fix(current_sequence): no error if not found (#3740)

* fix: login checkbox contrast, login policy factors, asset urls (#3742)

* checkbox contrast

* idp create before remove, add, asset service

* login policy events

Co-authored-by: Fabi <38692350+hifabienne@users.noreply.github.com>

* fix(query): show views and failed events (#3743)

* fix(system): show views and failed events

* fix: set correct database on failed events and views

* fix(console): application grid overflow (#3744)

* fix: use css grid instead of flex

* ellipsis overflow

Co-authored-by: Fabi <38692350+hifabienne@users.noreply.github.com>

* fix(projection): add missing col to idp login policy links (#3745)

* fix(projection): add missing col to projection

* refactor: method naming

* fix(console): get idps from login policy, add policy if not existent (#3746)

* fix: return correct empty flow if not found (#3749)

* feat: get current label and privacy policies (#3748)

* chore(console): dependencies (#3730)

* cli, core

* material, cdk

* chore(deps-dev): bump karma-jasmine-html-reporter from 1.7.0 to 2.0.0 in /console (#3722)

chore(deps-dev): bump karma-jasmine-html-reporter in /console

Bumps [karma-jasmine-html-reporter](https://github.com/dfederm/karma-jasmine-html-reporter) from 1.7.0 to 2.0.0.
- [Release notes](https://github.com/dfederm/karma-jasmine-html-reporter/releases)
- [Commits](https://github.com/dfederm/karma-jasmine-html-reporter/compare/v1.7.0...v2.0.0)

---
updated-dependencies:
- dependency-name: karma-jasmine-html-reporter
  dependency-type: direct:development
  update-type: version-update:semver-major
...

Signed-off-by: dependabot[bot] <support@github.com>

Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com>

* chore(deps-dev): bump @typescript-eslint/parser from 5.25.0 to 5.26.0 in /console (#3717)

chore(deps-dev): bump @typescript-eslint/parser in /console

Bumps [@typescript-eslint/parser](https://github.com/typescript-eslint/typescript-eslint/tree/HEAD/packages/parser) from 5.25.0 to 5.26.0.
- [Release notes](https://github.com/typescript-eslint/typescript-eslint/releases)
- [Changelog](https://github.com/typescript-eslint/typescript-eslint/blob/main/packages/parser/CHANGELOG.md)
- [Commits](https://github.com/typescript-eslint/typescript-eslint/commits/v5.26.0/packages/parser)

---
updated-dependencies:
- dependency-name: "@typescript-eslint/parser"
  dependency-type: direct:development
  update-type: version-update:semver-minor
...

Signed-off-by: dependabot[bot] <support@github.com>

Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com>

* chore(deps): bump libphonenumber-js from 1.10.4 to 1.10.6 in /console (#3716)

Bumps [libphonenumber-js](https://gitlab.com/catamphetamine/libphonenumber-js) from 1.10.4 to 1.10.6.
- [Release notes](https://gitlab.com/catamphetamine/libphonenumber-js/tags)
- [Changelog](https://gitlab.com/catamphetamine/libphonenumber-js/blob/master/CHANGELOG.md)
- [Commits](https://gitlab.com/catamphetamine/libphonenumber-js/compare/v1.10.4...v1.10.6)

---
updated-dependencies:
- dependency-name: libphonenumber-js
  dependency-type: direct:production
  update-type: version-update:semver-patch
...

Signed-off-by: dependabot[bot] <support@github.com>

Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com>

* jasmine

* lock

Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com>
Co-authored-by: Livio Amstutz <livio.a@gmail.com>

* fix: compatibility for cockroach v22.1 (#3754)

* fix: compatability for cockroach v22.1

* update cr version in docs and compose

* bind dev cockroach to 127.0.0.1

* Revert "bind dev cockroach to 127.0.0.1"

This reverts commit 1c7c6304ae.

* remove --listen-addr flag

* use v2.0.0-v2-alpha.16

* use v2.0.0-v2-alpha.17

Co-authored-by: Elio Bischof <eliobischof@gmail.com>

* fix: render only base language in html (#3759)

* fix: sql error check (#3762)

* docs: Docs v2 (#3733)

* fix: change images

* fix: change images, add policies

* fix: change images, add policies

* docs: add customer portal docs

* docs: add customer portal docs

* docs: add customer portal docs

* docs: add customer portal docs

* docs: organization creation

* docs: policy docs

* docs: change password

* docs: verify domain

* docs: profile page

* docs: profile page

* docs: profile page

* docs: login page

* docs: login page

* docs: fix broken links

* docs: customer portal users

* docs: instance detail

* docs: instance detail

* docs: getting started

* Update organizations.mdx

Co-authored-by: Livio Amstutz <livio.a@gmail.com>

* fix(console, login): Idp detail and create layout optimization, login - sub formfield link spacing (#3755)

* idp detail, create layout

* fat finger fix

Co-authored-by: Livio Amstutz <livio.a@gmail.com>

* fix: handle default org id (#3769)

* fix: update user sessions after avatar or primary domain change (#3768)

* fix: grpc gateway interceptors (#3767)

* fix: improve oidc issuer / endpoints (#3753)

* fix: improve oidc issuer / endpoints

* docs: update endpoints

* fix(console): datepicker, formfield cleanup, member role help, domain layout (#3765)

* key datepicker, formfield cleanup, member role help, domain layout

* accounts card template overlay

* fix account card trigger

* chore(deps-dev): bump @typescript-eslint/parser from 5.26.0 to 5.27.0 in /console (#3752)

chore(deps-dev): bump @typescript-eslint/parser in /console

Bumps [@typescript-eslint/parser](https://github.com/typescript-eslint/typescript-eslint/tree/HEAD/packages/parser) from 5.26.0 to 5.27.0.
- [Release notes](https://github.com/typescript-eslint/typescript-eslint/releases)
- [Changelog](https://github.com/typescript-eslint/typescript-eslint/blob/main/packages/parser/CHANGELOG.md)
- [Commits](https://github.com/typescript-eslint/typescript-eslint/commits/v5.27.0/packages/parser)

---
updated-dependencies:
- dependency-name: "@typescript-eslint/parser"
  dependency-type: direct:development
  update-type: version-update:semver-minor
...

Signed-off-by: dependabot[bot] <support@github.com>

Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com>

* deps, i18n, feature info section

* lint

Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com>

* fix(console, login): console - ensure permission is available, login - i18n fixes, input borders, lgn-touched script to add class on blur  (#3760)

* permission restriction, member, login i18n input borders, secondary text

* add touched js

* test: ensure consistency of TestSpooler_awaitError (#3750)

* docs: add gitlab and auth0 (#3700)

* docs: add gitlab and auth0

* Apply suggestions from code review

* fix wrong domain

* Apply suggestions from code review

Co-authored-by: mffap <mpa@zitadel.com>

* fix redirect-uris

* typos

* replace image wip

* smaller typos

* Update docs/docs/guides/basics/applications.mdx

Co-authored-by: mffap <mpa@zitadel.com>

* Update docs/docs/guides/basics/applications.mdx

Co-authored-by: mffap <mpa@zitadel.com>

Co-authored-by: Fabi <38692350+hifabienne@users.noreply.github.com>
Co-authored-by: mffap <mpa@zitadel.com>
Co-authored-by: Maximilian Panne <mpa@caos.ch>
Co-authored-by: Livio Spring <livio.a@gmail.com>

* feat: return instance domains on list instances, fix: login policy and avatar url in oidc responses (#3785)

* feat: return instance domains on list instances

* fix: filter login policy idps correctly

* remove debug

* fix: absolute avatar url in oidc responses

* fix: allow project grants without roles in database (#3786)

* fix: password check policy correctly (#3787)

* fix: password check policy correctly

* fix: password check policy correctly

* docs: Identity providers and customer portal (#3790)

* docs: identity provider and customer portal page

* docs: identity provider and customer portal page

* docs: identity provider and customer portal page

* docs: urls

* fix: add smtp config, remove smtp and sms provider, console adaptations (#3792)

* fix: add AddSMTPConfig to admin api

* addsmtpconfig

* fix: add RemoveSMTPConfig and RemoveSMSProvider to admin api

* update twilio, token fcn

* fix account switcher, twilio token set, cleanup dialog

* cleanup

* buttons

Co-authored-by: Livio Amstutz <livio.a@gmail.com>

* fix(console, login): label policy and privacy policy from authservice, login - remove double footer element, mobile (#3795)

fix: cnsl auth policy, lgn footer mobile

* docs: change architecture graphic (#3794)

* fix(console): configWithPrompt cleanup (#3796)

* fix: configWithPrompt cleanup

* code dialog text

Co-authored-by: Livio Spring <livio.a@gmail.com>

* fix: set instanceID correctly in org project mapping (#3789)

* fix: idp styling (#3797)

* fix: idp styling

* escape idp a color

* elevation on hover

* css gen

Co-authored-by: Max Peintner <max@caos.ch>

* fix: allow env vars to override setup defaults (#3800)

* fix: sms providers (#3801)

* fix(login): idp, link font color (#3814)

fix: idp, a font color

* fix(console): remove basepath from statehandler (#3815)

fix: remove basepath from statehandler

* fix(query): realtime data on defined requests (#3726)

* feat: directly specify factors on addCustomLoginPolicy and return on LoginPolicy responses

* fix proto

* update login policy

* feat: directly specify idp on addCustomLoginPolicy and return on LoginPolicy responses

* fix: tests

* fix(projection): trigger bulk

* refactor: clean projection pkg

* instance should bulk

* fix(query): should trigger bulk on id calls

* tests

* build prerelease

* fix: add shouldTriggerBulk

* fix: test

Co-authored-by: Livio Amstutz <livio.a@gmail.com>
Co-authored-by: Max Peintner <max@caos.ch>

* fix(system): search for existing domain globally (#3822)

* docs(legal): Updated agreements and policies v2 (#3823)

* tos

* adds cloud service

* cloud service description WIP

* action minute

* service level description

* SAML and last revised

* tos credit and payment

* dpa basic, profile, and payment data

* service description: authenticated requests

* cloud service description: ui

* add notification box

* sla description

* support services

* removes dedicated instance annex

* remove dedicated instance annex sidebar, links

* update dedicated terms

* merge additional terms in sidebar

* privacy formatting

* pp update piid table

* remove cloudflare cookies

* privacy customer portal cookies

* revert editing guides

* dates

* docs: test

* modification of services

* Apply suggestions from code review

Co-authored-by: Fabi <38692350+hifabienne@users.noreply.github.com>

* add disclaimer to regions list

Co-authored-by: Maximilian Panne <mpa@caos.ch>
Co-authored-by: Maximilian Panne <maximilian.panne@gmail.com>
Co-authored-by: mffap <mpa@zitadel.com>

* fix(notify): fail if required fields are empty (#3831)

* fix(login): text color for idp, footer (#3830)

Co-authored-by: Fabi <38692350+hifabienne@users.noreply.github.com>

* fix(auth): read user if not found after create (#3835)

* fix(notify): correct get user (#3836)

* feat: enable insecure console for custom domains (#3819)

* fix: enable insecure console

* Revert "fix: enable insecure console"

This reverts commit e6c10ae937.

* don't require HTTPS for non-localhost domains

Co-authored-by: Max Peintner <max@caos.ch>

* docs: update ZITADEL cloud readme (#3849)

* docs: update ZITADEL cloud readme

* Update README.md

* Update README.md

Co-authored-by: mffap <mpa@zitadel.com>

Co-authored-by: mffap <mpa@zitadel.com>

* docs: add curl for introspection_endpoint with basic auth (#3851)

* docs: update api introduction (#3781)

* fix: update oidc pkg (state and redirect_uri handling) (#3853)

* chore(console): add customer portal link (#3837)

* feat: add customer portal link

* add customer portal to environment.json from backend

Co-authored-by: Livio Amstutz <livio.a@gmail.com>

* feat: TLS support (#3862)

* feat: TLS support

* add comment

* fix comment

* chore: set tleMode disabled in docker compose (#3865)

* chore(docs): fix typo (#3866)

* fix: primary domain scope (handle context correctly) (#3872)

* feat: provide instance info on admin api and return version on instances responses (admin and system api) (#3802)

* feat: provide instance info on admin api and return version on instances responses (admin and system api)

* fix GetMyInstance

* fix: enable env vars in setup steps (and deprecate admin subcommand) (#3871)

* fix: enable env vars in setup steps (and deprecate admin subcommand)

* fix tests and error text

* chore(console): angular 14 (#3799)

* eslint schematics

* cli, core migrations

* material

* schematics

* ng-qrcode update

* fix input, formfield errorstatemixin

* other packages

* downgrade codemirror

* codemirror

* @next of alphas

Co-authored-by: Livio Spring <livio.a@gmail.com>

* docs(installation): improve guides (#3817)

* split config descriptions

* install and configure

* custom domains

* typo

* remove comments

* try compose with secure crdb

* secure crdb with compose

* describe ExternalSecure restriction

* add near production example

* add login credentials

* fix configure compose

* make the docs more transparent

* name archive amd64

* Revert "name archive amd64"

This reverts commit 0d4dae551b.

* fix download url

* extract archives

* fix dawin download

* fix start zitadel commands

* add helm installation docs

* remove windows

* make downloaded files description friendlier

* link to github raw

* link login process

* remove healthcheck from compose

* remove compose healthchecks

* use --tlsMode external for lb example

* uname -i

* disable tls mode locally

* Update docs/docs/guides/installation/get-started/macos.mdx

Co-authored-by: Fabi <38692350+hifabienne@users.noreply.github.com>

Co-authored-by: Fabi <38692350+hifabienne@users.noreply.github.com>

* docs(guides): user metadata (#3838)

* docs(guides): user metadata

* add python

* export to BASIC_AUTH

* add js

* add alternative with id_token

* fix img path

* adds reserved scopes, and info about opaque token

* Apply suggestions from code review

Co-authored-by: Elio Bischof <eliobischof@gmail.com>

* Apply suggestions from code review

Co-authored-by: Elio Bischof <eliobischof@gmail.com>

Co-authored-by: Maximilian Panne <mpa@caos.ch>
Co-authored-by: Elio Bischof <eliobischof@gmail.com>

* docs(installation): knative (#3860)

* added initial knative docu

* added menu bar

* simplified installation

* normalized versions to latest

* update envs

* update envs

* Update zitadel-knative-service.yaml

* Update knative.mdx

* Update knative.mdx

* move knative into correct folder

Co-authored-by: Livio Spring <livio.a@gmail.com>

* docs(installation): fix overview items (#3880)

* docs(installation): fix overview items

* installation after getting started

* fix broken links

* fix broken links

* fix broken link

* docs(installation): fix guides (#3878)

* docs(installation): download traefik config

* docs(installation): remove unnecessary zitadel user certs

* docs(installation): fix broken link (#3883)

* docs: edit instance docs (#3885)

* chore: contributing console

Co-authored-by: Livio Amstutz <livio.a@gmail.com>
Co-authored-by: Fabi <38692350+hifabienne@users.noreply.github.com>
Co-authored-by: Florian Forster <florian@caos.ch>
Co-authored-by: Silvan <silvan.reusser@gmail.com>
Co-authored-by: mffap <mpa@zitadel.com>
Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com>
Co-authored-by: Elio Bischof <eliobischof@gmail.com>
Co-authored-by: Maximilian Panne <mpa@caos.ch>
Co-authored-by: Maximilian Panne <maximilian.panne@gmail.com>
Co-authored-by: Nicolas Hedger <649677+nhedger@users.noreply.github.com>
Co-authored-by: Christian Jakob <47860090+thesephirot@users.noreply.github.com>

* describe local frontend development

* finish local frontend dev

* ignore environment.json

* redirect environment.json to file

* add context and teardown information

* omit installation of dev dependencies

* unskip remove project tests

* build base image

* use network_mode host for e2e container

* quote uid

* add backend contribution guide

* typo

* note on cypress xserver with wsl2

* add links

* build custom cypress image

* remove --help

* Revert "remove --help"

This reverts commit 14b50bc48b.

* Revert "build custom cypress image"

This reverts commit bc2caaac9c.

* remove dot

* Update CONTRIBUTING.md

Co-authored-by: Florian Forster <florian@zitadel.com>

Co-authored-by: Maximilian Panne <mpa@caos.ch>
Co-authored-by: Florian Forster <florian@caos.ch>
Co-authored-by: Max Peintner <max@caos.ch>
Co-authored-by: Livio Amstutz <livio.a@gmail.com>
Co-authored-by: Fabi <38692350+hifabienne@users.noreply.github.com>
Co-authored-by: Silvan <silvan.reusser@gmail.com>
Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com>
Co-authored-by: Elio Bischof <eliobischof@gmail.com>
Co-authored-by: Nicolas Hedger <649677+nhedger@users.noreply.github.com>
Co-authored-by: Christian Jakob <47860090+thesephirot@users.noreply.github.com>
Co-authored-by: Florian Forster <florian@zitadel.com>
2022-08-26 19:39:15 +02:00

15 KiB

Contributing to ZITADEL

Introduction

Thank you for your interest about how to contribute! As you might know there is more than code to contribute. You can find all information needed to start contributing here.

Please give us and our community the chance to get rid of security vulnerabilities by responsibly disclose this kind of issues by contacting security@zitadel.com.

The strongest part of a community is the possibility to share thoughts. That's why we try to react as soon as possible to your ideas, thoughts and feedback. We love to discuss as much as possible in an open space like in the issues and discussions section here or in our chat, but we understand your doubts and provide further contact options here.

If you want to give an answer or be part of discussions please be kind. Treat others like you want to be treated. Read more about our code of conduct here.

What can I contribute?

For people who are new to ZITADEL: We flag issues which are a good starting point to start contributing. You find them here

Make ZITADEL more popular and give it a

Help shaping the future of ZITADEL:

Contribute

Follow @zitadel on twitter

How to contribute

We strongly recommend to talk to us before you start contributing to streamline our and your work.

We accept contributions through pull requests. You need a github account for that. If you are unfamiliar with git have a look at Github's documentation on creating forks and creating pull requests. Please draft the pull request as soon as possible. Go through the following checklist before you submit the final pull request:

Submit a Pull Request (PR)

  1. Fork the zitadel/zitadel repository on GitHub
  2. On your fork, commit your changes to a new branch

git checkout -b my-fix-branch main

  1. Make your changes following the guidelines in this guide. Make sure that all tests pass.

  2. Commit the changes on the new branch

git commit --all

  1. Merge the latest commit of the main-branch

  2. Push the changes to your branch on Github

git push origin my-fix-branch

  1. Use Semantic Release commit messages to simplify creation of release notes. In the title of the pull request correct tagging is required and will be requested by the reviewers.

  2. On GitHub, send a pull request to zitadel:main. Request review from one of the maintainers.

Reviewing a Pull Request

The reviewers will provide you feedback and approve your changes as soon as they are satisfied. If we ask you for changes in the code, you can follow the GitHub Guide to incorporate feedback in your pull request.

Commit Messages

Make sure you use semantic release messages format.

<type>(<scope>): <short summary>

Type

Must be one of the following:

  • feat: New Feature
  • fix: Bug Fix
  • docs: Documentation

Scope

This is optional to indicate which component is affected. In doubt, leave blank (<type>: <short summary>)

Short Summary

Provide a brief description of the change.

Contribute

The code consists of the following parts:

name description language where to find
backend Service that serves the grpc(-web) and RESTful API go API implementation
console Frontend the user interacts with after he is logged in Angular, Typescript ./console
login Server side rendered frontend the user interacts with during login go, go templates ./internal/api/ui/login
API definitions Specifications of the API Protobuf ./proto/zitadel
docs Project documentation made with docusaurus Docusaurus ./docs

Please validate and test the code before you contribute.

We add the label "good first issue" for problems we think are a good starting point to contribute to ZITADEL.

Backend / Login

By executing the commands from this section, you run everything you need to develop the ZITADEL backend locally. Using Docker Compose, you run a CockroachDB on your local machine. With goreleaser, you build a debuggable ZITADEL binary and run it using delve. Then, you test your changes via the console your binary is serving at http://localhost:8080 and by verifying the database. Once you are happy with your changes, you run end-to-end tests and tear everything down.

The commands in this section are tested against the following software versions:

Make some changes to the source code, then run the database locally.

# You just need the db service to develop the backend against.
docker compose --file ./e2e/docker-compose.yaml up --detach db

Build the binary. This takes some minutes, but you can speed up rebuilds.

# You just need goreleasers build part (--snapshot) and you just need to target your current platform (--single-target)
goreleaser build --id dev --snapshot --single-target --rm-dist --output .artifacts/zitadel/zitadel

Note: With this command, several steps are executed. For speeding up rebuilds, you can reexecute only specific steps you think are necessary based on your changes.
Generating gRPC stubs: DOCKER_BUILDKIT=1 docker build -f build/zitadel/Dockerfile . --target go-copy -o .
Running unit tests: DOCKER_BUILDKIT=1 docker build -f build/zitadel/Dockerfile . --target go-codecov
Generating the console: DOCKER_BUILDKIT=1 docker build -f build/console/Dockerfile . -t zitadel-npm-console --target angular-export -o internal/api/ui/console/static/
Build the binary: goreleaser build --id dev --snapshot --single-target --rm-dist --output .artifacts/zitadel/zitadel --skip-before

You can now run and debug the binary in .artifacts/zitadel/zitadel using your favourite IDE, for example GoLand. You can test if ZITADEL does what you expect by using the UI at http://localhost:8080/ui/console. Also, you can verify the data by running cockroach sql --database zitadel --insecure and running SQL queries.

As soon as you are ready to battle test your changes, run the end-to-end tests.

# Build the production binary (unit tests are executed, too)
goreleaser build --id prod --snapshot --single-target --rm-dist --output .artifacts/zitadel/zitadel

# Pack the binary into a docker image
DOCKER_BUILDKIT=1 docker build --file build/Dockerfile .artifacts/zitadel -t zitadel:local

# Run the tests
ZITADEL_IMAGE=zitadel:local docker compose --file ./e2e/docker-compose.yaml run e2e

When you are happy with your changes, you can cleanup your environment.

# Stop and remove the docker containers for zitadel and the database
docker compose --file ./e2e/docker-compose.yaml down

Console

By executing the commands from this section, you run everything you need to develop the console locally. Using Docker Compose, you run CockroachDB and the latest release of ZITADEL on your local machine. You use the ZITADEL container as backend for your console. The console is run in your Node environment using a local development server for Angular, so you have fast feedback about your changes. Once you are happy with your changes, you run end-to-end tests and tear everything down.

The commands in this section are tested against the following software versions:

Note for WSL2 on Windows 10 Following the suggestions here subsequently here may need to XLaunch and configure your DISPLAY variable. Use at your own risk.
  1. Install VcXsrv Windows X Server
  2. Set the target of your shortcut to "C:\Program Files\VcXsrv\xlaunch.exe" -ac
  3. In WSL2 run export DISPLAY=$(cat /etc/resolv.conf | grep nameserver | awk '{print $2}'):0 to set your DISPLAY variable
  4. When starting XLaunch, make sure to disable access control

Run the database and the latest backend locally.

# Change to the console directory
cd ./console

# You just need the db and the zitadel services to develop the console against.
docker compose --file ../e2e/docker-compose.yaml up --detach db zitadel

When the backend is ready, you have the latest zitadel exposed at http://localhost:8080. You can now run a local development server with live code reloading at http://localhost:4200. To allow console access via http://localhost:4200, you have to configure the ZITADEL backend.

  1. Navigate to http://localhost:8080/ui/console/projects.
  2. When prompted, login with zitadel-admin@zitadel.localhost and Password1!
  3. Select the ZITADEL project.
  4. Select the Console application.
  5. Select Redirect Settings
  6. Add http://localhost:4200/auth/callback to the Redirect URIs
  7. Add http://localhost:4200/signedout to the Post Logout URIs
  8. Select the Save button

You can run the local console development server now.

# Console loads its target environment from the file console/src/assets/environment.json.
# Load it from the backend.
curl http://localhost:8080/ui/console/assets/environment.json > ./src/assets/environment.json

# Generate source files from Protos
npm run generate

# Install npm dependencies
npm install

# Start the server
npm start

Navigate to http://localhost:4200/. Make some changes to the source code and see how the browser is automatically updated. After making changes to the code, you should run the end-to-end-tests. Open another shell.

# Change to the e2e directory
cd .. && cd e2e/

# Install npm dependencies
npm install

# Run all tests in a headless browser
npm run e2e:dev

You can also open the test suite interactively for fast success feedback on specific tests.

# Run all tests in a headless browser
npm run open:dev

When you are happy with your changes, you can cleanup your environment

# Stop and remove the docker containers for zitadel and the database
docker compose down

Contribute Docs

Project documentation is made with docusaurus and is located under ./docs. Please refer to the README for more information and local testing.

When making a pull request use docs(<scope>): <short summary> as title for the semantic release. Scope can be left empty (omit the brackets) or refer to the top navigation sections.

Contribute Internationalization

ZITADEL loads translations from four files:

You may edit the texts in these files or create a new file for additional language support. Make sure you set the locale (ISO 639-1 code) as the name of the new language file.

Want to start ZITADEL?

You can find an installation guide for all the different environments here: https://docs.zitadel.com/docs/guides/installation

Did you find a security flaw?