mirror of
https://github.com/zitadel/zitadel.git
synced 2025-01-05 22:52:46 +00:00
a6e4b537fe
* chore(contributing): add startup * init * cleanup docker file * local * compose works * markdowns * add gateway start on readme * readme done * finish mds * rename/delete compose files * correct docker compose file name * fix links, update contribute, split build/readme into separate files in /guides, add zitadel startup * fix(docker compose): allow .keys folder to not exist * update md's * use docker-compose instead of docker compose as --profile gets ignored * write a message if create key * copy openapi statik.go * explain how to connect in quickstart * Apply suggestions from code review Co-authored-by: Livio Amstutz <livio.a@gmail.com> * sremove subscription service from env.json * Delete caos_local.sh moved to build/local/local.env Co-authored-by: Livio Amstutz <livio.a@gmail.com>
154 lines
4.6 KiB
Markdown
154 lines
4.6 KiB
Markdown
# Development
|
|
|
|
You should stay in the ZITADEL root directory to execute the statements in the following chapters.
|
|
|
|
## Prerequisite
|
|
|
|
- Buildkit compatible docker installation
|
|
|
|
### env variables
|
|
|
|
You can use the default vars provided in [this .env-file](../build/local/local.env) or create your own and update the paths in the [docker compose file](../build/local/docker-compose-local.yml).
|
|
|
|
## Generate required files
|
|
|
|
This part is relevant if you start the backend or console without docker compose.
|
|
|
|
### Console
|
|
|
|
This command generates the grpc stub for console into the folder console/src/app/proto/generated for local development.
|
|
|
|
```bash
|
|
DOCKER_BUILDKIT=1 docker build -f build/dockerfile . -t zitadel:gen-fe --target npm-copy -o .
|
|
```
|
|
|
|
### Backend
|
|
|
|
With this command you can generate the stub for the backend.
|
|
|
|
```bash
|
|
# generates grpc stub
|
|
DOCKER_BUILDKIT=1 docker build -f build/dockerfile . -t zitadel:gen-be --target go-copy -o .
|
|
# generates keys for cryptography
|
|
DOCKER_BUILDKIT=1 docker build --target copy_keys -f build/Dockerfile.dev . -o .keys
|
|
```
|
|
|
|
## Run
|
|
|
|
### Initialise data
|
|
|
|
Used if you want to setup the database and load the initial data.
|
|
|
|
```bash
|
|
COMPOSE_DOCKER_CLI_BUILD=1 DOCKER_BUILDKIT=1 docker-compose -f ./build/local/docker-compose-local.yml --profile database --profile init-backend -p zitadel up
|
|
```
|
|
|
|
You can stop as soon as db-migrations AND backend-setup returned with exit code 0.
|
|
|
|
### Initialise frontend
|
|
|
|
Used to set the client id of the console. This step is for local development. If you don't work with a local backend you have to set the client id manually.
|
|
|
|
You must [initialise the data](###-Initialise-data)) first.
|
|
|
|
```bash
|
|
COMPOSE_DOCKER_CLI_BUILD=1 DOCKER_BUILDKIT=1 docker-compose -f ./build/local/docker-compose-local.yml --profile database --profile backend --profile init-frontend -p zitadel up --exit-code-from client-id
|
|
```
|
|
|
|
The command exists as soon as the client id is set.
|
|
|
|
### Run database
|
|
|
|
Used if you want to run the backend/console locally and only need the database. It's recommended to [initialise the data](###-Initialise-data) first.
|
|
|
|
```bash
|
|
COMPOSE_DOCKER_CLI_BUILD=1 DOCKER_BUILDKIT=1 docker-compose -f ./build/local/docker-compose-local.yml --profile database -p zitadel up
|
|
```
|
|
|
|
**On apple silicon:**
|
|
Restart the command (second terminal `docker restart zitadel_<SERVICE_NAME>_1`) if `db` logs `qemu: uncaught target signal 11 (Segmentation fault) - core dumped` or no logs are written from `db-migrations`.
|
|
|
|
### Run Console
|
|
|
|
The console service is configured for hot reloading. You can also use docker compose for local development.
|
|
|
|
If you don't use the backend from local you have to configure [the environment.json](../build/local/environment.json) manually.
|
|
|
|
If you use the local backend ensure that you have [set the correct client id](###-Initialise-frontend).
|
|
|
|
#### Run console in docker compose
|
|
|
|
```bash
|
|
COMPOSE_DOCKER_CLI_BUILD=1 DOCKER_BUILDKIT=1 docker-compose -f ./build/local/docker-compose-local.yml --profile frontend -p zitadel up
|
|
```
|
|
|
|
### Run backend
|
|
|
|
Used if you want to run the backend locally. It's recommended to [initialise the data](###-Initialise-data) first.
|
|
|
|
#### Run backend in docker compose
|
|
|
|
```bash
|
|
COMPOSE_DOCKER_CLI_BUILD=1 DOCKER_BUILDKIT=1 docker-compose -f ./build/local/docker-compose-local.yml --profile database --profile backend -p zitadel up
|
|
```
|
|
|
|
#### Run backend locally
|
|
|
|
##### Export environment variables
|
|
|
|
```bash
|
|
# exports all default env variables
|
|
while read line; do
|
|
if [[ $line != #* ]] && [[ ! -z $line ]]; then
|
|
export $line
|
|
fi
|
|
done < build/local/local.env
|
|
```
|
|
|
|
##### Start command for backend
|
|
|
|
```bash
|
|
# starts zitadel with default config files
|
|
go run cmd/zitadel/main.go -console=false -localDevMode=true -config-files=cmd/zitadel/startup.yaml -config-files=cmd/zitadel/system-defaults.yaml -config-files=cmd/zitadel/authz.yaml start
|
|
```
|
|
|
|
If you want to run your backend locally and the frontend by docker compose you have to replace the following variables:
|
|
|
|
[docker compose yaml](../build/local/docker-compose-local.yml):
|
|
|
|
```yaml
|
|
service:
|
|
client-id:
|
|
environment:
|
|
- HOST=backend-run
|
|
grpc-web-gateway:
|
|
environment:
|
|
- BKD_HOST=backend-run
|
|
```
|
|
|
|
with
|
|
|
|
```yaml
|
|
service:
|
|
client-id:
|
|
environment:
|
|
- HOST=host.docker.internal
|
|
grpc-web-gateway:
|
|
environment:
|
|
- BKD_HOST=host.docker.internal
|
|
```
|
|
|
|
##### Setup ZITADEL
|
|
|
|
The following command starts the backend of ZITADEL with the default config files:
|
|
|
|
```bash
|
|
go run cmd/zitadel/main.go -setup-files=cmd/zitadel/setup.yaml -setup-files=cmd/zitadel/system-defaults.yaml -setup-files=cmd/zitadel/authz.yaml setup
|
|
```
|
|
|
|
## Initial login credentials
|
|
|
|
**username**: `zitadel-admin@caos-ag.zitadel.ch`
|
|
|
|
**password**: `Password1!`
|