Sam Rolfe
b4bbd6d3f9
- README: Phase 9 status, the architecture diagram + map link, and the explicit "Teams (FR-15) is DEFERRED" statement. - docs/architecture.mmd + docs/diagrams/architecture.png (mmdc). - docs/archify/architecture.architecture.json -> docs/architecture-map.html (Archify showcase, 9/9 checks). - docs/outline/: the five AI-context documents (STE style). - docs/vikunja-tasks.json: the live Vikunja board (project 21). Co-Authored-By: Paperclip <noreply@paperclip.ing>
102 lines
3.7 KiB
Markdown
102 lines
3.7 KiB
Markdown
# Compass NHS — Configuration and Environment
|
|
|
|
## Rules for Agents
|
|
|
|
1. Never write a credential, token, cookie or session value into a document.
|
|
2. Keep every secret in `environment.d/school-service.env`. The file is gitignored.
|
|
3. Copy the shape from `environment.d/school-service.env.example`. Never copy a value.
|
|
4. Docker Compose interpolates `$VAR` inside `env_file`. Escape each bcrypt `$` as `$$`.
|
|
|
|
## Paths
|
|
|
|
| Item | Path |
|
|
| :--- | :--- |
|
|
| Real env file | `environment.d/school-service.env` |
|
|
| Env example | `environment.d/school-service.env.example` |
|
|
| Config code | `internal/config/` |
|
|
| SQLite schema | `internal/store/migrations/` |
|
|
| Service binary | `/app/school` inside the container |
|
|
| Database | `/data/school.db` inside the container |
|
|
| Docker volume | `compass-teams-nhs-data` |
|
|
|
|
## Ports
|
|
|
|
| Port | System | Host |
|
|
| :--- | :--- | :--- |
|
|
| 8792 | This service | `.13` |
|
|
| 8210 | Apprise API | `.35` |
|
|
| 8788 | Hub inbound API | `.13` |
|
|
| 8123 | Home Assistant | `.30` |
|
|
| 5678 | n8n | `.13` |
|
|
|
|
Caddy on `.35` publishes `school.lab.audasmedia.com.au` and proxies to
|
|
`192.168.20.13:8792`.
|
|
|
|
## Variables
|
|
|
|
### Service
|
|
|
|
| Variable | Meaning |
|
|
| :--- | :--- |
|
|
| `SCHOOL_ADDR` | Listen address. Default `:8792`. |
|
|
| `SCHOOL_DB_PATH` | SQLite path. Container value `/data/school.db`. |
|
|
| `SCHOOL_SESSION_SECRET` | Signs the session cookie. Secret. Minimum 16 characters. |
|
|
| `SCHOOL_ADMIN_USERNAME` | The single dashboard login. |
|
|
| `SCHOOL_ADMIN_PASSWORD_HASH` | Bcrypt hash. Prefer this over the plaintext. |
|
|
| `SCHOOL_ADMIN_PASSWORD` | Plaintext fallback. |
|
|
| `SCHOOL_COOKIE_SECURE` | `true` behind HTTPS. |
|
|
| `SCHOOL_SESSION_TTL` | Session life. Default `12h`. |
|
|
| `SCHOOL_TIMEZONE` | Family timezone for due dates. |
|
|
| `SCHOOL_LOG_LEVEL` | Log level. |
|
|
| `SCHOOL_APP_ENV` | Environment name. |
|
|
|
|
### Home Assistant Calendar
|
|
|
|
| Variable | Meaning |
|
|
| :--- | :--- |
|
|
| `SCHOOL_HA_URL` | Home Assistant base URL. |
|
|
| `SCHOOL_HA_TOKEN` | Long-lived access token. Secret. |
|
|
| `SCHOOL_HA_CALENDAR_ENTITY` | Calendar entity. Default `calendar.school`. |
|
|
| `SCHOOL_HA_INSECURE` | Skips TLS verification. Use only for the internal `.lab` URL. |
|
|
| `SCHOOL_HA_TIMEOUT` | Per-request timeout. Default `20s`. |
|
|
|
|
### Apprise
|
|
|
|
| Variable | Meaning |
|
|
| :--- | :--- |
|
|
| `SCHOOL_APPRISE_URL` | Apprise API base. Default `http://192.168.20.35:8210`. |
|
|
| `SCHOOL_APPRISE_KEY` | Stored configuration key. Secret. |
|
|
| `SCHOOL_APPRISE_TOKEN` | Optional bearer token. |
|
|
| `SCHOOL_APPRISE_TIMEOUT` | Per-request timeout. Default `15s`. |
|
|
| `SCHOOL_APPRISE_CHANNELS` | `email,whatsapp`. |
|
|
| `SCHOOL_APPRISE_TAGS` | Recipients as `Name=tag-base`. |
|
|
| `SCHOOL_APPRISE_PARENTS` | Who receives the combined brief. `Jo,Sam`. |
|
|
| `SCHOOL_NOTIFY_TOKEN` | Bearer token for `POST /notify/morning`. Secret. |
|
|
|
|
### Hub API
|
|
|
|
| Variable | Meaning |
|
|
| :--- | :--- |
|
|
| `SCHOOL_HUB_TOKEN` | Shared bearer token. Secret. Empty turns the Hub endpoints off with `503`. |
|
|
|
|
The Hub holds the same token as `HUB_PROJECT_COMPASS_NHS_TOKEN`. The Hub reaches
|
|
this service through `HUB_PROJECTS=compass_nhs=http://192.168.20.13:8792`.
|
|
|
|
## Secrets Outside This Repo
|
|
|
|
| Secret | Location |
|
|
| :--- | :--- |
|
|
| Apprise destinations (address, number, SMTP) | Apprise stored configuration on `.35` |
|
|
| Hub token copy | `~/.config/environment.d/10-secrets.conf` on `.13` |
|
|
| Compass account and password | Paperclip secret or the env file |
|
|
| n8n trigger SSH key | `/home/sam/.ssh/id_ed25519_school_scan` |
|
|
|
|
The Apprise destinations stay outside this repo on purpose. This service names a
|
|
tag such as `harry_email` only.
|
|
|
|
## Environment Access for an Agent
|
|
|
|
The service does not scan the school. n8n runs `scripts/morning-brief.sh`
|
|
through a restricted SSH key. The key has a forced command and `restrict`. It
|
|
cannot open a shell.
|