Files
ZitPlane/docs/DEVELOPMENT.md
T

37 lines
2.5 KiB
Markdown
Raw Normal View History

# 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.