38 lines
2.5 KiB
Markdown
38 lines
2.5 KiB
Markdown
# Developer quick guide
|
|
|
|
## Current status
|
|
- P01 Foundation: committed.
|
|
- P02 Local backend: configuration and helper implemented; **runtime verification blocked** because Docker is not installed on the connected Windows PC.
|
|
- No customized Login V2 or Account Portal source has been imported yet.
|
|
|
|
## Getting local ZITADEL running
|
|
1. Install and launch Docker Desktop with Linux containers. Verify `docker compose version`.
|
|
2. Open PowerShell in `ZitPlane`.
|
|
3. Run `py core/backend/zitadel/dev.py init` once. This creates ignored local `.env` with random credentials; **never put secrets in Git**.
|
|
4. Run `py core/backend/zitadel/dev.py config` to validate Compose after Docker is installed.
|
|
5. Run `py core/backend/zitadel/dev.py up` to pull/start official images and verify `/debug/ready`.
|
|
6. Visit `http://localhost:8080/ui/console`. Log in as `zitadel-admin@zitadel.localhost` using the private generated initial password; change it as prompted.
|
|
7. Use `py core/backend/zitadel/dev.py down` to stop without destroying PostgreSQL or bootstrap-token volumes.
|
|
|
|
The proxy is **loopback-only and HTTP-only**. It is for disposable local development, not shared network access or Coolify. Read `core/backend/zitadel/README.md` for expected persistence and limitations.
|
|
|
|
## Where to change code (future phases)
|
|
- Official Go server: **no core source edits**, see `core/backend/zitadel/`.
|
|
- Auth UI changes: `auth/ui/v2/` after P03 import.
|
|
- Account UI changes: `users/ui/` after P04.
|
|
- Shared UI/components: `packages/` only if required by imported code.
|
|
- Local Docker infrastructure: `deployment/docker/`.
|
|
|
|
## Development/production separation
|
|
The P02 file `deployment/docker/compose.backend.dev.yaml` is not the production Compose file. Production secrets, HTTPS routing, remote domains, Admin access security, backup/restore and Coolify deployment are reserved for later approved phases. The dev master key and data **must never** be reused in production.
|
|
|
|
## Local checks
|
|
```powershell
|
|
py -m unittest discover -s tests -p test_backend_dev.py -v
|
|
git diff --check
|
|
```
|
|
A green stdlib-only test means only that local config and secret-generation contracts passed; it does **not** mean Docker images booted or authentication worked.
|
|
|
|
## AI Studio and coding agents
|
|
Allow AI to modify layout/components/styles only in approved UI scopes. Never replace ZITADEL session, OAuth, MFA or passkey logic with mocks. Do not use real credentials in screenshots/prompts. Run approved UI regression tests before integration.
|