How updates work — start here

For anyone new: what you want to change → where to edit it → how to push it live yourself → or what to tell Claude to do it for you.

The map — where everything lives

"I want to change…"

1. The website / dashboard (a page, button, the board builder)

Where to edit: /var/www/cloudpoynt/public/… on the server (e.g. builder.html, js/boards.js, css/…).

Push it live (manual):

ssh -i ~/.ssh/openclaw-keys/checkpoynt-server.pem ubuntu@98.84.86.23
cd /var/www/cloudpoynt
nano public/<file>            # edit — LIVE the moment you save (no build step)
git add public/<file> && git commit -m "why: <what changed>" && git push

Then hard-refresh the browser (Cmd/Ctrl+Shift+R).

Tell Claude: "On the boards page, make the Save button …" / "Fix the builder so …"

2. The API / backend (an endpoint, a bug in server logic)

Where to edit: /var/www/api.cloudpoynt/src/… — controllers/, routes/, middleware/, utils/.

Push it live (manual):

cd /var/www/api.cloudpoynt
nano src/controllers/<file>.js
node --check src/controllers/<file>.js     # catch syntax errors
npm test                                   # guard tests must pass
pm2 restart api                            # ⚠️ the API is DEAD until you restart it
curl https://api.cloudpoynt.com/health     # confirm it came back
git add src/<file> && git commit -m "why: …" && git push

Tell Claude: "Add an endpoint that …" / "Fix the heartbeat handler so …"

3. The database

A setting / a person's access (data): easiest in this dashboard, or a SQL UPDATE (e.g. make someone admin: UPDATE users SET role='admin' WHERE email='…').

A new column / table (schema): add a numbered file migrations/NNN_description.sql, back up first (mysqldump), apply by hand, and keep it additive only (new columns NULL DEFAULT NULL; never DROP).

Tell Claude: "Make alex@example.com an admin" / "Add a phone column to customers"

4. The display screens (Pi code) and over-the-air updates

The most careful one — a bad push can break TVs in the field. Never update the whole fleet at once.

Quick fix to ONE screen (scp):

scp pi/display_service.py digitalboards:/home/checkpoynt/display/display_service.py
ssh digitalboards 'sudo systemctl restart display-service'

Ship to the fleet (OTA) — the safe order:

1. Cut a new release dir /home/ubuntu/display-pi-source/releases/X.Y.Z/ (bump APP_VERSION, write version.json with a sha256 per file).
2. Validate: node tools/validate-version.js /home/ubuntu/display-pi-source/releases/X.Y.Z.
3. Canary ONE live screen — admin → Display Devices → Push Update on a single device. Watch it 15–30 min.
4. Only if healthy, fan out a few at a time. (Push Update All hits everyone — don't use it for a rollout.)

Tell Claude: "Canary display version X to one Pi, watch it, then roll out."

5. What's on the screens (assign a board, push content, rename a device)

No code needed — use this dashboard (admin account): assign a board/playlist/menu to a display, rename or remove a device, push updates, manage users.

Tell Claude: "Put board BOARD-1234 on the lobby screen" / "Rename DSP-… to 'Front window'."

What to tell Claude (cheat-sheet)

Claude does either route for you and follows this whole procedure — runs the tests, commits to Gitea, restarts what needs restarting, and stops to ask before anything risky (restarting the live POS API, pushing to real screens). Just say what you want:

• "Fix <bug> on <page/endpoint> and push it."
• "Make <email> an admin."
• "Ship <change> to the displays — canary first."
• "What changed in the API in the last week?" (it reads Gitea history)
• "Is everything committed / is anything not deployed?"

The five rules that keep this safe

1. Always git push to Gitea — it's the only history.
2. API changes need pm2 restart api — nothing happens until you restart.
3. Website is live on save — be careful, there's no staging.
4. Database changes are additive only — back up first, never DROP.
5. Screens: canary one, watch, then fan out — never push to the whole fleet at once.

Source of truth: cloudpoynt-boards/docs/HOW-UPDATES-WORK.md in Gitea (full discipline in BUILD-TEST-DEPLOY-PLAYBOOK.md). Edit there and keep this page in sync.