Files

Sam Rolfe b4bbd6d3f9 Phase 9: publish the documentation set (README, map, Outline, Vikunja)

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

2026-10-15 20:00:23 +11:00

3.7 KiB

Raw Blame History

Compass NHS — Configuration and Environment

Rules for Agents

Never write a credential, token, cookie or session value into a document.
Keep every secret in environment.d/school-service.env. The file is gitignored.
Copy the shape from environment.d/school-service.env.example. Never copy a value.
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.

3.7 KiB Raw Blame History