compass_teams_nhs/docs/phase-7a-n8n-schedule.md

Phase 7a — the 6:00am n8n schedule (AUD-115)

Phase 7 (AUD-111) proved the delivery path: POST /notify/morning, the per-boy and combined briefs, the Apprise channels, and eight real deliveries. This phase makes the schedule real: one n8n workflow that runs every day at 06:00 and sends the briefs.

What the workflow is

deploy/n8n-morning-brief.json is a four-node workflow:

Schedule Trigger  "0 6 * * *"  (Australia/Melbourne) ─┐
                                                       ├─▶  SSH node  ──▶  Code check
Manual Trigger  "Run now (manual)"  ───────────────────┘    (restricted key)

• SSH node — authenticates to .13 as sam with the restricted trigger key and runs the brief on the host. The scan needs node + patchright on .13, so it cannot run inside the n8n container.
• Code node — the SSH node returns the remote exit code but does not fail on it. The Code node throws when code !== 0, so a failed scan or send turns the n8n execution red (FR-12).
• Manual Trigger — optional. It lets Sam run the brief by hand from the n8n UI, or with docker exec n8n n8n execute --id=schoolMorningBrf. The schedule fires on its own; the manual trigger only does something when pressed.

scripts/morning-brief.sh is the bounded command. It scans both children, builds the per-boy and combined briefs, sends them through Apprise, and exits non-zero when the scan or a send fails. The brief always opens with the failure when the scan failed — never "nothing due".

The run needs no SCHOOL_NOTIFY_TOKEN in n8n. The token stays in environment.d/school-service.env, which the host script reads.

Why not an Execute Command node

The first design used one n8n-nodes-base.executeCommand node. It cannot work on this instance. n8n 2.x disables that node by default for security (nodes.exclude = ['n8n-nodes-base.executeCommand', 'n8n-nodes-base.localFileTrigger']). An imported workflow with it is marked active in the database but never activates:

Activation of workflow "Compass / NHS — 6:00am morning brief" (schoolMorningBrf) did fail
  with error: "Unrecognized node type: n8n-nodes-base.executeCommand"

The same error affects the pre-existing Tree Info workflow. The SSH node is enabled and, with the restricted key, runs exactly one command — so it is both workable and least-privilege. Enabling Execute Command instead would need NODES_EXCLUDE=[] in the shared n8n service, which re-enables arbitrary shell execution for every workflow.

The SSH trigger key and credential

The n8n container mounts /home/sam/.ssh at /home/node/.ssh. The trigger uses a dedicated key with a forced command, so it can run exactly one thing:

restrict,command="cd /home/sam/paseo/projects/compass_teams_nhs && ./scripts/morning-brief.sh" ssh-ed25519 AAAA…

• restrict disables pty, agent forwarding, port forwarding, X11, and shell access.
• command= makes the server ignore whatever command the client sends.
• The private key lives at /home/sam/.ssh/id_ed25519_school_scan (mode 0600) and is readable only by sam and the n8n container (which already mounts ~/.ssh).
• The key is not Sam's personal key and is not used anywhere else.

Create the key with:

deploy/setup-n8n-scan-key.sh            # dry run: print the plan
deploy/setup-n8n-scan-key.sh --apply    # create the key + the authorized_keys line

The SSH node needs the private key in an n8n credential (sshPrivateKey, id schoolScanKey). deploy/import-n8n-morning-brief.sh builds that credential from the key file into a mode-0600 temp file, imports it, and removes it. The key is never written into this repository.

Import and activate

deploy/import-n8n-morning-brief.sh            # dry run: print the plan
deploy/import-n8n-morning-brief.sh --apply    # credential + workflow, publish, restart n8n

The script imports the credential, copies the JSON into the container with docker exec -i … sh -c 'cat > …' (docker cp fails against the ~/.ssh mount), runs n8n import:workflow, then n8n publish:workflow --id=schoolMorningBrf (n8n 2.x replaced update:workflow --active), restarts n8n once so the 06:00 schedule registers, and confirms the n8n log shows the workflow activated — the database's active flag alone is not proof.

The JSON carries a stable id (schoolMorningBrf). n8n 2.18.5 refuses an import whose workflow has no id (SQLITE_CONSTRAINT: NOT NULL constraint failed: workflow_entity.id), so the id is required, not cosmetic. Re-importing the same file updates the same workflow instead of adding a second copy.

n8n publish:workflow prints "Changes will not take effect if n8n is running", which is why the import script restarts n8n once. The full import → activate → run and the failure path were rehearsed in a throwaway n8n container with a temporary data directory, using the same n8n 2.18.5 image, before the change was proposed. The shared instance was not touched for the rehearsal.

Verification

docker logs n8n | grep 'Activated workflow "Compass / NHS'
docker exec n8n n8n list:workflow --active=true      # schoolMorningBrf is listed
docker exec compass-teams-nhs /app/school notify status

Rehearsal evidence (throwaway container, same image):

• activation: Activated workflow "school ssh rehearsal" — no Unrecognized node type
• success path (forced command echo): status: success
• failure path (forced command exit 7): status: error, CLI exit 1, message morning-brief.sh failed with exit 7

A healthy morning looks like this in notify status:

1 Harry   Harry   email    ok  <date> 06:0x
2 Harry   Harry   whatsapp ok  <date> 06:0x
3 Finn    Finn    email    ok  <date> 06:0x
4 Finn    Finn    whatsapp ok  <date> 06:0x
5 combined Jo     email    ok  <date> 06:0x
6 combined Jo     whatsapp ok  <date> 06:0x
7 combined Sam    email    ok  <date> 06:0x
8 combined Sam    whatsapp ok  <date> 06:0x

Proving a run

The Schedule Trigger only fires at 06:00, so the schedule is proved by the activation log line plus the next morning's notify status rows. To prove the full send path without waiting, run the published workflow once by hand:

docker exec n8n n8n execute --id=schoolMorningBrf

This sends the real briefs, so run it only when a real delivery is wanted. n8n execute starts from the Manual Trigger; both trigger paths reach the same SSH node.

Not touched

• Compass / Teams: read-only. Nothing in this phase writes to the school.
• Other n8n workflows: untouched.
• n8n's global node configuration: untouched. Execute Command stays disabled.
• Secrets: no address, phone number, Apprise key, session secret, or notify token is written into the workflow JSON, this document, or git. The SSH private key lives in an n8n credential and the host authorized_keys, never in the repository.