From 9693ed44550ca6b68b0b0c972f1172f7122de6f9 Mon Sep 17 00:00:00 2001 From: Elio Bischof Date: Mon, 24 Oct 2022 08:43:24 +0200 Subject: [PATCH] docs(contributing): remove guides folder (#4603) --- console/README.md | 2 +- guides/development.md | 150 ------------------------------------------ guides/production.md | 13 ---- guides/quickstart.md | 71 -------------------- 4 files changed, 1 insertion(+), 235 deletions(-) delete mode 100644 guides/development.md delete mode 100644 guides/production.md delete mode 100644 guides/quickstart.md diff --git a/console/README.md b/console/README.md index 0d866f178c..7147c0487b 100644 --- a/console/README.md +++ b/console/README.md @@ -20,7 +20,7 @@ Run `ng test` to execute the unit tests via [Karma](https://karma-runner.github. ## Running end-to-end tests -Please refer to [guides](../guides/quickstart.md#developing-zitadel) +Please refer to the [contributing guide](../CONTRIBUTING.md#console) ## Further help diff --git a/guides/development.md b/guides/development.md deleted file mode 100644 index 3efbb75020..0000000000 --- a/guides/development.md +++ /dev/null @@ -1,150 +0,0 @@ -# Development - -You should stay in the ZITADEL root directory to execute the statements in the following chapters. - -## Prerequisite - -- Buildkit compatible docker installation -- [go](https://go.dev/doc/install) -- [goreleaser](https://goreleaser.com/install/) - -Minimum resources: - -- CPU's: 2 -- Memory: 4Gb - -### Installing goreleaser - -If you get the error `Failed to fetch https://repo.goreleaser.com/apt/Packages Certificate verification failed: The certificate is NOT trusted. The certificate chain uses expired certificate.` while installing goreleaser with `apt`, then ensure that ca-certificates are installed: - -```sh -sudo apt install ca-certificates -``` - -## Local Build - -Simply run goreleaser to build locally. This will generate all the required files, such as angular and grpc automatically. - -```sh -export DOCKER_BUILDKIT=1 -goreleaser build --snapshot --rm-dist --single-target -``` - -## Production Build & Release - -Simply use goreleaser: - -```sh -goreleaser release -``` - -## Run - -### Start storage - -Use this if you only want to start the storage services needed by ZITADEL. These services are started in background (detached). - -```bash -COMPOSE_DOCKER_CLI_BUILD=1 DOCKER_BUILDKIT=1 \ -&& docker compose -f ./build/local/docker-compose-local.yml --profile storage up -d -``` - -**On apple silicon:** -Restart the command (second terminal `docker restart zitadel__1`) if `db` logs `qemu: uncaught target signal 11 (Segmentation fault) - core dumped` or no logs are written from `db-migrations`. - -### Initialize the console - -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 console-stub up --exit-code-from client-id -``` - -The command exists as soon as the client id is set. - -### Start the 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 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 storage --profile backend 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!` diff --git a/guides/production.md b/guides/production.md deleted file mode 100644 index 5d4c879042..0000000000 --- a/guides/production.md +++ /dev/null @@ -1,13 +0,0 @@ -# Production Build - -To create a production build to run locally, create a snapshot release with goreleaser: - -```sh -goreleaser release --snapshot --rm-dist -``` - -This can be released to production (if you have credentials configured) using gorelease as well: - -```sh -goreleaser release -``` diff --git a/guides/quickstart.md b/guides/quickstart.md deleted file mode 100644 index 01a4b25616..0000000000 --- a/guides/quickstart.md +++ /dev/null @@ -1,71 +0,0 @@ -# Quickstart with docker compose - -## Prerequisites - -The only prerequisite you need fullfill, is that you need to have docker installed with support for compose and buildkit. The resource limit must at least be: - -* CPU's: 2 -* Memory: 4Gb - -## Start ZITADEL - -You can start ZITADEL with a simple docker compose up. - -The services are configured to restart if an error occurs. - -In the following script the basic setup of the database is executed before ZITADEL starts. Execute the statement from the root of ZITADEL. - -You can connect to [ZITADEL on localhost:4200](http://localhost:4200) after the frontend compiled successfully. Initially it takes several minutes to start all containers. - -```bash -COMPOSE_DOCKER_CLI_BUILD=1 DOCKER_BUILDKIT=1 \ -&& docker compose -f ./build/local/docker-compose-local.yml --profile backend --profile frontend up -``` - -For a more detailed guide take a look at the [development guide](./development.md) - -## FAQ - -### Mac M1 (Apple Silicon) - -Bellow are some errors we faced with apple silicon. - -#### database-migrations don't start or stop without exit code - -You can simply restart the database with the following command: - -```bash -COMPOSE_DOCKER_CLI_BUILD=1 DOCKER_BUILDKIT=1 \ -&& docker compose -f ./build/local/docker-compose-local.yml restart db -``` - -#### API call's block and don't return any response - -The problem is that the database has a connection issues. You can simply restart the database with the following command: - -```bash -COMPOSE_DOCKER_CLI_BUILD=1 DOCKER_BUILDKIT=1 \ -&& docker compose -f ./build/local/docker-compose-local.yml restart db -``` - -### Build Errors - -If you experience strange docker error you might need to check that `buildkit` is enabled. - -Make sure to enable `"features": { "buildkit": true }` in your docker settings! - -### Remove the quickstart - -```Bash -docker-compose -f ./build/local/docker-compose-local.yml --profile database --profile init-backend --profile init-frontend --profile backend --profile frontend rm -``` - -If you are **confident** that you don't need to run the same ZITADEL instance again, go ahead and delete the `.keys` folder and reset the `environment.json` as well. - -```Bash -rm -rf .keys -``` - -```Bash -git reset build/local/environment.json -```