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