diff --git a/.devcontainer/base/devcontainer.json b/.devcontainer/base/devcontainer.json index 187e012e67..0a0d9d95ee 100644 --- a/.devcontainer/base/devcontainer.json +++ b/.devcontainer/base/devcontainer.json @@ -3,6 +3,10 @@ "name": "devcontainer", "dockerComposeFile": "docker-compose.yml", "service": "devcontainer", + "runServices": [ + "devContainer", + "db" + ], "workspaceFolder": "/workspaces", "features": { "ghcr.io/devcontainers/features/go:1": { @@ -25,4 +29,4 @@ } } } -} +} \ No newline at end of file diff --git a/.devcontainer/login-integration-debug/devcontainer.json b/.devcontainer/login-integration-debug/devcontainer.json index 010969858a..0ba4d5dc7f 100644 --- a/.devcontainer/login-integration-debug/devcontainer.json +++ b/.devcontainer/login-integration-debug/devcontainer.json @@ -14,7 +14,7 @@ 3001 ], "onCreateCommand": "pnpm install --recursive && cd apps/login/integration && pnpm cypress install", - "postAttachCommand": "pnpm turbo daemon clean || true; pnpm turbo test:integration:login:debug", + "postAttachCommand": "pnpm turbo daemon clean || true; pnpm turbo test:integration:login", "customizations": { "jetbrains": { "settings": { diff --git a/.devcontainer/login-integration/devcontainer.json b/.devcontainer/login-integration/devcontainer.json index 1b7e02df43..663e02e5c3 100644 --- a/.devcontainer/login-integration/devcontainer.json +++ b/.devcontainer/login-integration/devcontainer.json @@ -5,9 +5,13 @@ "../base/docker-compose.yml" ], "service": "devcontainer", - "runServices": ["login-integration"], + "runServices": [ + "login-integration" + ], "workspaceFolder": "/workspaces", - "forwardPorts": [3001], + "forwardPorts": [ + 3001 + ], "onCreateCommand": "pnpm install --frozen-lockfile --recursive && cd apps/login/packages/integration && pnpm cypress install && pnpm test:integration:login", "customizations": { "jetbrains": { @@ -16,4 +20,4 @@ } } } -} +} \ No newline at end of file diff --git a/.devcontainer/turbo-lint-unit-debug/devcontainer.json b/.devcontainer/turbo-lint-unit-debug/devcontainer.json index 19446687a1..9323503971 100644 --- a/.devcontainer/turbo-lint-unit-debug/devcontainer.json +++ b/.devcontainer/turbo-lint-unit-debug/devcontainer.json @@ -10,7 +10,7 @@ "workspaceFolder": "/workspaces", "forwardPorts": [3001], "onCreateCommand": "pnpm install --recursive", - "postAttachCommand": "pnpm turbo daemon clean; pnpm turbo watch lint test:unit", + "postAttachCommand": "pnpm turbo daemon clean || true; pnpm turbo watch lint test:unit", "customizations": { "jetbrains": { "settings": { diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 4c1ae53072..b83d1f8518 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,6 +1,5 @@ # 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. @@ -150,51 +149,19 @@ The API is designed to be used by different clients, such as web applications, m Therefore, the API is designed to be easy to use, consistent, and reliable. Please check out the dedicated [API guidelines](./API_DESIGN.md) page when contributing to the API. - -#### Developing Zitadel with Dev Containers - -You can use dev containers if you'd like to make sure you have the same development environment like the corresponding GitHub PR checks use. -The following dev containers are available: - -- **.devcontainer/base/devcontainer.json**: Contains everything you need to run whatever you want. -- **.devcontainer/turbo-lint-unit/devcontainer.json**: Runs a dev container that executes frontent linting and unit tests and then exits. This is useful to reproduce the corresponding GitHub PR check. -- **.devcontainer/turbo-lint-unit-debug/devcontainer.json**: Runs a dev container that executes frontent linting and unit tests in watch mode. You can fix the errors right away and have immediate feedback. -- **.devcontainer/login-integration/devcontainer.json**: Runs a dev container that executes login integration tests and then exits. This is useful to reproduce the corresponding GitHub PR check. -- **.devcontainer/login-integration-debug/devcontainer.json**: Runs a dev container that spins up the login in a hot-reloading dev server and executes login integration tests interactively. You can fix the errors right away and have immediate feedback. - -You can also run the GitHub PR checks locally in dev containers without having to connect to a dev container. - - -The following pnpm commands use the [devcontainer CLI](https://github.com/devcontainers/cli/) and exit when the checks are done. -The minimal system requirements are having Docker and the devcontainers CLI installed. -If you don't have the node_modules installed already, you need to install the devcontainers CLI manually. Run `npm i -g @devcontainers/cli`. Alternatively, the [official Microsoft VS Code extension for Dev Containers](https://marketplace.visualstudio.com/items?itemName=ms-vscode-remote.remote-containers) offers a command `Dev Containers: Install devcontainer CLI` - - -```bash -npm run devcontainer:lint-unit -npm run devcontainer:integration:login -``` - -If you don't have NPM installed, copy and execute the scripts from the package.json directly. - -To connect to a dev container to have full IDE support, follow the instructions provided by your code editor/IDE to initiate the dev container. -This typically involves opening the "Command Palette" or similar functionality and searching for commands related to "Dev Containers" or "Remote Containers". -The quick start guide for VS Code can found [here](https://code.visualstudio.com/docs/devcontainers/containers#_quick-start-open-an-existing-folder-in-a-container) - -For example, to build and run the Zitadel binary in a dev container, connect your IDE to the dev container described in .devcontainer/base/devcontainer.json. -Run the following commands inside the container to start Zitadel. - -```bash -make compile && ./zitadel start-from-init --masterkey MasterkeyNeedsToHave32Characters --tlsMode disabled -``` - -Zitadel serves traffic as soon as you can see the following log line: - -`INFO[0001] server is listening on [::]:8080` - ## Contribute Backend Code + + +### Backend Requirements + By executing the commands from this section, you run everything you need to develop the Zitadel backend locally. + +> [!INFO] +> Some [dev containers are available](dev-containers) for remote development with docker and pipeline debugging in isolated environments. +> If you don't want to use one of the dev containers, you can develop the backend components directly on your local machine. +> To do so, proceed with installing the necessary dependencies. + Using [Docker Compose](https://docs.docker.com/compose/), you run a [PostgreSQL](https://www.postgresql.org/download/) on your local machine. With [make](https://www.gnu.org/software/make/), you build a debuggable Zitadel binary and run it using [delve](https://github.com/go-delve/delve). Then, you test your changes via the console your binary is serving at http://localhost:8080 and by verifying the database. @@ -208,6 +175,8 @@ The commands in this section are tested against the following software versions: - [Go version 1.22](https://go.dev/doc/install) - [Delve 1.9.1](https://github.com/go-delve/delve/tree/v1.9.1/Documentation/installation) +### Build and Run Zitadel + Make some changes to the source code, then run the database locally. ```bash @@ -588,6 +557,48 @@ For the turbo commands, check your options with `pnpm turbo --help` | `pnpm turbo down` | Remove containers and volumes | Shut down containers from the integration test setup `pnpm turbo down` | | `pnpm turbo clean` | Remove downloaded dependencies and other generated files | Remove generated docs `pnpm turbo clean --filter zitadel-docs` | +## Developing Zitadel with Dev Containers + +You can use dev containers if you'd like to make sure you have the same development environment like the corresponding GitHub PR checks use. +The following dev containers are available: + +- **.devcontainer/base/devcontainer.json**: Contains everything you need to run whatever you want. +- **.devcontainer/turbo-lint-unit/devcontainer.json**: Runs a dev container that executes frontent linting and unit tests and then exits. This is useful to reproduce the corresponding GitHub PR check. +- **.devcontainer/turbo-lint-unit-debug/devcontainer.json**: Runs a dev container that executes frontent linting and unit tests in watch mode. You can fix the errors right away and have immediate feedback. +- **.devcontainer/login-integration/devcontainer.json**: Runs a dev container that executes login integration tests and then exits. This is useful to reproduce the corresponding GitHub PR check. +- **.devcontainer/login-integration-debug/devcontainer.json**: Runs a dev container that spins up the login in a hot-reloading dev server and executes login integration tests interactively. You can fix the errors right away and have immediate feedback. + +You can also run the GitHub PR checks locally in dev containers without having to connect to a dev container. + + +The following pnpm commands use the [devcontainer CLI](https://github.com/devcontainers/cli/) and exit when the checks are done. +The minimal system requirements are having Docker and the devcontainers CLI installed. +If you don't have the node_modules installed already, you need to install the devcontainers CLI manually. Run `npm i -g @devcontainers/cli`. Alternatively, the [official Microsoft VS Code extension for Dev Containers](https://marketplace.visualstudio.com/items?itemName=ms-vscode-remote.remote-containers) offers a command `Dev Containers: Install devcontainer CLI` + + +```bash +npm run devcontainer:lint-unit +npm run devcontainer:integration:login +``` + +If you don't have NPM installed, copy and execute the scripts from the package.json directly. + +To connect to a dev container to have full IDE support, follow the instructions provided by your code editor/IDE to initiate the dev container. +This typically involves opening the "Command Palette" or similar functionality and searching for commands related to "Dev Containers" or "Remote Containers". +The quick start guide for VS Code can found [here](https://code.visualstudio.com/docs/devcontainers/containers#_quick-start-open-an-existing-folder-in-a-container) + +For example, to build and run the Zitadel binary in a dev container, connect your IDE to the dev container described in .devcontainer/base/devcontainer.json. +Run the following commands inside the container to start Zitadel. + +```bash +make compile && ./zitadel start-from-init --masterkey MasterkeyNeedsToHave32Characters --tlsMode disabled +``` + +Zitadel serves traffic as soon as you can see the following log line: + +`INFO[0001] server is listening on [::]:8080` + + ## Contribute Translations Zitadel loads translations from four files: @@ -608,11 +619,6 @@ You also have to add some changes to the following files: - [Customized Text Docs](./docs/docs/guides/manage/customize/texts.md) - [Add language option](./internal/api/ui/login/static/templates/external_not_found_option.html) -## Want to start Zitadel? - -You can find an installation guide for all the different environments here: -[https://zitadel.com/docs/self-hosting/deploy/overview](https://zitadel.com/docs/self-hosting/deploy/overview) - ## **Did you find a security flaw?** - Please read [Security Policy](./SECURITY.md). diff --git a/apps/login/.gitignore b/apps/login/.gitignore index 17a18bf973..c4fe97a6f5 100644 --- a/apps/login/.gitignore +++ b/apps/login/.gitignore @@ -2,6 +2,7 @@ custom-config.js .env*.local standalone tsconfig.tsbuildinfo +cypress .DS_Store node_modules diff --git a/apps/login/cypress.config.ts b/apps/login/cypress.config.ts index e245c7df1c..6d35d44c50 100644 --- a/apps/login/cypress.config.ts +++ b/apps/login/cypress.config.ts @@ -2,7 +2,6 @@ import { defineConfig } from "cypress"; export default defineConfig({ reporter: "list", - e2e: { baseUrl: process.env.LOGIN_BASE_URL || "http://localhost:3001/ui/v2/login", specPattern: "integration/integration/**/*.cy.{js,jsx,ts,tsx}", diff --git a/apps/login/integration/fixtures/example.json b/apps/login/integration/fixtures/example.json deleted file mode 100644 index 02e4254378..0000000000 --- a/apps/login/integration/fixtures/example.json +++ /dev/null @@ -1,5 +0,0 @@ -{ - "name": "Using fixtures to represent data", - "email": "hello@cypress.io", - "body": "Fixtures are a great way to mock data for responses to routes" -} diff --git a/apps/login/package.json b/apps/login/package.json index fd5f4a4380..30a5b4112c 100644 --- a/apps/login/package.json +++ b/apps/login/package.json @@ -15,8 +15,7 @@ "test:unit": "vitest --run", "lint-staged": "lint-staged", "clean": "rm -rf .turbo && rm -rf node_modules && rm -rf .next", - "test:integration:login": "DISPLAY='' cypress run", - "test:integration:login:debug": "DISPLAY=:0 cypress open", + "test:integration:login": "wait-on http://localhost:3001/ui/v2/login && DISPLAY='' cypress run", "test:acceptance": "dotenv -e ../login/.env.test.local playwright", "test:acceptance:setup": "cd ../.. && make login_test_acceptance_setup_env && NODE_ENV=test turbo run test:acceptance:setup:dev", "test:acceptance:setup:dev": "cd ../.. && make login_test_acceptance_setup_dev" @@ -54,6 +53,11 @@ "devDependencies": { "@babel/eslint-parser": "^7.23.0", "@bufbuild/buf": "^1.53.0", + "@faker-js/faker": "^9.7.0", + "@otplib/core": "^12.0.0", + "@otplib/plugin-crypto": "^12.0.0", + "@otplib/plugin-thirty-two": "^12.0.0", + "@playwright/test": "^1.52.0", "@testing-library/jest-dom": "^6.6.3", "@testing-library/react": "^16.3.0", "@types/ms": "2.1.0", @@ -67,34 +71,30 @@ "@vercel/git-hooks": "1.0.0", "@vitejs/plugin-react": "^4.4.1", "autoprefixer": "10.4.21", + "concurrently": "^9.1.2", + "cypress": "^14.5.2", + "dotenv-cli": "^8.0.0", + "env-cmd": "^10.0.0", "eslint": "^8.57.0", "eslint-config-next": "15.4.0-canary.86", "eslint-config-prettier": "^9.1.0", + "gaxios": "^7.1.0", "grpc-tools": "1.13.0", "jsdom": "^26.1.0", "lint-staged": "15.5.1", "make-dir-cli": "4.0.0", + "nodemon": "^3.1.9", "postcss": "8.5.3", "prettier": "^3.2.5", "prettier-plugin-organize-imports": "^3.2.0", "prettier-plugin-tailwindcss": "0.6.11", "sass": "^1.87.0", + "start-server-and-test": "^2.0.11", "tailwindcss": "3.4.14", "ts-proto": "^2.7.0", "typescript": "^5.8.3", "vite-tsconfig-paths": "^5.1.4", "vitest": "^2.0.0", - "concurrently": "^9.1.2", - "cypress": "^14.5.2", - "dotenv-cli": "^8.0.0", - "env-cmd": "^10.0.0", - "nodemon": "^3.1.9", - "start-server-and-test": "^2.0.11", - "@faker-js/faker": "^9.7.0", - "@otplib/core": "^12.0.0", - "@otplib/plugin-crypto": "^12.0.0", - "@otplib/plugin-thirty-two": "^12.0.0", - "@playwright/test": "^1.52.0", - "gaxios": "^7.1.0" + "wait-on": "^7.2.0" } } \ No newline at end of file diff --git a/apps/login/turbo.json b/apps/login/turbo.json index 58d5ad6891..a9265b2f12 100644 --- a/apps/login/turbo.json +++ b/apps/login/turbo.json @@ -40,9 +40,16 @@ "@zitadel/client#build" ] }, - "test:integration:login:debug": { - "persistent": true, - "cache": false, + "test:integration:login": { + "inputs": [ + ".next/trace", + "integration/integration/**", + "integration/support/**" + ], + "outputs": [ + "cypress/videos/**", + "cypress/screenshots/**" + ], "with": [ "dev" ] diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml index f86339aa1e..4c69ce9d42 100644 --- a/pnpm-lock.yaml +++ b/pnpm-lock.yaml @@ -224,6 +224,9 @@ importers: vitest: specifier: ^2.0.0 version: 2.1.9(@types/node@22.16.5)(jsdom@26.1.0)(less@4.1.3)(lightningcss@1.30.1)(sass@1.89.2)(terser@5.43.1) + wait-on: + specifier: ^7.2.0 + version: 7.2.0 console: dependencies: @@ -22819,7 +22822,7 @@ snapshots: copy-webpack-plugin@11.0.0(webpack@5.100.2(@swc/core@1.13.1(@swc/helpers@0.5.17))): dependencies: - fast-glob: 3.3.3 + fast-glob: 3.3.1 glob-parent: 6.0.2 globby: 13.2.2 normalize-path: 3.0.0