You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
`Bind for :::5432 failed: port is already allocated` means another stack holds the port — stop it or don't start the colliding service. Worktrees get **parallel compose projects** (project name = directory name) but fight over the same host ports; only one stack variant runs per machine.
57
57
58
-
## Check 6 — infra bring-up (headless-safe)
58
+
## Check 6 — infra bring-up / server status (headless-safe)
59
+
60
+
Depending on your environment path:
61
+
62
+
### Path A: Inside Devcontainer
63
+
64
+
The container manages infra services and app servers automatically in the background. Check logs and process status:
65
+
66
+
```bash
67
+
pgrep -f "turbo run dev">/dev/null &&echo"Dev servers running"||echo"Dev servers NOT running"
68
+
tail -n 50 /tmp/dev.log # inspect server startup logs
69
+
```
70
+
71
+
If servers are down, restart them: `bash .devcontainer/post-start.sh`.
72
+
73
+
### Path B: Host-based Setup
74
+
75
+
Manually boot the compose infrastructure:
59
76
60
77
```bash
61
78
docker compose config --quiet # resolves WITHOUT secrets (verified)
62
79
docker compose up -d postgres redis_exec redis_assessment redis_cache mailhog hatchet
63
80
docker compose ps # everything Started/healthy?
64
81
```
65
82
66
-
Config-derived continuation for app work: `.github/scripts/wait-for-infra.sh`, then `./util/_create_hatchet_token.sh`, then `pnpm run prisma:push`. Traefik path (`*.klicker.com`) additionally needs `/etc/hosts` entries, mkcert certs (`util/_create_ssl_certificates.sh`), and the `reverse_proxy_<os>` service.
83
+
Continuation for app work: `.github/scripts/wait-for-infra.sh`, then `./util/_create_hatchet_token.sh`, then `pnpm run --filter @klicker-uzh/prisma prisma:push`. Traefik path (`*.klicker.com`) additionally needs `/etc/hosts` entries, mkcert certs (`util/_create_ssl_certificates.sh`), and the `reverse_proxy_<os>` service.
- No Next.js middleware for CSP/headers — that belongs at the proxy layer.
20
-
3.**Verify in the browser — mandatory, not optional.** You are authorized to start the dev servers needed for this verification (and must clean up after with `./_down.sh`):
21
-
- Bring-up per [docs/getting-started.md](../../../docs/getting-started.md) (localhost `dev:raw` path works without secrets); on failure → `klicker-environment-doctor`.
20
+
3.**Verify in the browser — mandatory, not optional.** Depending on your environment path:
21
+
-**Inside Devcontainer:** Dev servers auto-start in the background. No need to start/stop them. View logs via `tail -f /tmp/dev.log`.
22
+
-**Host-based Setup:** You are authorized to start the dev servers needed for this verification, and must clean up after with `./_down.sh`. Bring-up per [docs/getting-started.md](../../../docs/getting-started.md) (localhost `dev:raw` path works without secrets).
23
+
- On bring-up / server failure → `klicker-environment-doctor`.
22
24
- Open the changed pages with `npx agent-browser` (never bare `agent-browser`), log in via **delegated** access with the AGENTS.md test credentials (not Edu-ID).
23
25
- Capture before/after screenshots of every changed state (including error/empty states you touched); check both locales if strings changed.
24
26
- Iterate on issues you see yourself; hand to the user for manual verification only after your own pass succeeds.
Copy file name to clipboardExpand all lines: AGENTS.md
+1-1Lines changed: 1 addition & 1 deletion
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -123,7 +123,7 @@ Prisma split-schema under `packages/prisma/src/prisma/schema/`. After editing a
123
123
124
124
### Self-contained devcontainer (recommended)
125
125
126
-
Clone-and-run via a self-contained devcontainer — no Infisical/Doppler, no EduID, no `/etc/hosts` edits. The container owns the whole stack (Node 20 + pnpm toolchain, Postgres, 3× Redis, MailHog, Hatchet) and runs **all core apps in ONE container** via `turbo dev`. Run pnpm/prisma/tests **inside the container**, never on the host.
126
+
Clone-and-run via a self-contained devcontainer — no Infisical/Doppler, no EduID, no `/etc/hosts` edits. The container owns the whole stack (Node 24 + pnpm toolchain, Postgres, 3× Redis, MailHog, Hatchet) and runs **all core apps in ONE container** via `turbo dev`. Run pnpm/prisma/tests **inside the container**, never on the host.
127
127
128
128
```bash
129
129
devpod up .# builds image, starts services, installs, builds, seeds, runs dev
Copy file name to clipboardExpand all lines: docs/getting-started.md
+33-4Lines changed: 33 additions & 4 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -14,13 +14,42 @@ tags:
14
14
15
15
## Toolchain (verified 2026-07-07)
16
16
17
-
Pinned in root `package.json`: `volta.node = 24.16.0`, `volta.pnpm = 11.5.0`, `packageManager = pnpm@11.5.0`. Ignore the "Node.js 20" claim in [AGENTS.md](../AGENTS.md) — it is stale. `packages/word-cloud` pins `engines.node = 20` and prints a warning under Node 24; harmless today.
17
+
Aligned to Node `24.16.0` and pnpm `11.5.0` across the entire workspace, including the self-contained devcontainer. Pinned in root `package.json`: `volta.node = 24.16.0`, `volta.pnpm = 11.5.0`, `packageManager = pnpm@11.5.0`.
Clone-and-run via a self-contained devcontainer — no Infisical, no external EduID, no `/etc/hosts` edits needed. The container runs all core apps via `turbo dev` and houses all dependencies (Postgres, Redis, MailHog, Hatchet).
26
+
27
+
1.**Start the container:**
28
+
```bash
29
+
devpod up .# builds image, starts services, installs, builds, seeds, runs dev
30
+
devpod ssh klicker-uzh # shell inside the container
31
+
```
32
+
2.**Accessing the apps:**
33
+
-**Mode 1 (Plain localhost - default):** Exposed directly on host ports: Student PWA at `http://localhost:3001`, Lecturer UI at `http://localhost:3002` (login: `lecturer`/`abcd`).
34
+
-**Mode 2 (devrouter overlay):** Routes local traffic over HTTPS: `https://manage.klicker.localhost`. Requires:
35
+
1. Edit `.devcontainer/devcontainer.json` to include the devrouter overlay:
3. Install `devrouter` on host and register the application routes:
41
+
```bash
42
+
for a in api auth pwa manage control olat-api response-api lti chat db; do dev app run "$a"; done
43
+
```
44
+
3. **Logs:** The dev servers auto-start inside the container. View logs via `tail -f /tmp/dev.log`.
45
+
46
+
### Path B: Host-based Setup (Legacy)
47
+
48
+
Runs all services on your host machine. Needs Traefik (`*.klicker.com` reverse proxy), mkcert, `/etc/hosts` configurations, and Infisical for secret injection.
20
49
21
50
```bash
22
-
pnpm --version # must print 11.x — see lead paragraph
23
-
pnpm install # ~20s cold; peer warnings in apps/docs + packages/prisma are pre-existing
51
+
pnpm --version # must print 11.x
52
+
pnpm install # ~20s cold; peer warnings are pre-existing
24
53
pnpm run build # 21 turbo tasks, ~1.5min; needs NO secrets
25
54
pnpm run check # typecheck — only passes AFTER build (generated artifacts)
0 commit comments