Files

tonym b8af0f986b docs: refresh README + CLAUDE.md for current modules; add deploy guide for any Claude

- README/CLAUDE.md: Inventory depth (warranty/value/maintenance/sold/custom fields,
  HomeBox CSV import), Locations page, the two-world data-model rule, API-first +
  service-layer conventions, and the HTTPS-gated future work (MCP/PWA/camera)
- New docs/git-deploy-guide.md: self-contained git + deploy walkthrough for a
  Claude instance working without this repo's CLAUDE.md (NAS is a git checkout,
  push + pull/rebuild, never rsync, secrets in host .env, prisma-at-runtime gotcha)

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

2026-06-16 01:27:30 -05:00

3.5 KiB

Raw Blame History

Editing & deploying Moon Base — a guide for any Claude instance

Read this if you're a Claude (or anyone) working on Moon Base without the full project CLAUDE.md in context — e.g. running on a different machine. It's the self-contained version of how to change the code and get it onto the live server.

The repo

Lives on the home NAS Gitea: http://192.168.0.5:3022/bonna61/Moonbase
Clone: git clone http://tonym:<TOKEN>@192.168.0.5:3022/bonna61/Moonbase.git (the API token lives in the workspace-level ~/Projects/CLAUDE.md — never commit it)
Default branch: master.

The golden rule: the NAS appdata is a GIT CHECKOUT, not a sync target

The running app on the NAS lives at /mnt/user/appdata/moonbase, which is a real git clone tracking origin/master. You deploy by pushing to Gitea, then pulling on the NAS — never by copying files. Do not rsync over the appdata dir; it fights the checkout and corrupts it.

How to make a change

Edit code in your local working copy.
Bump the version: set APP_VERSION in src/lib/version.ts and add a plain-English entry to the top of src/lib/changelog.ts — write it for Bonna (the non-technical user): what changed and why. Minor (0.X.0) for features/migrations, patch (0.0.X) for fixes. Docs-only changes don't need a bump.
Schema change? Create a migration: npx prisma migrate dev --create-only --name <slug>, review the SQL, then npx prisma migrate deploy locally. The server applies pending migrations automatically on container start.
Verify locally: npx tsc --noEmit and npm run test; run npx next build for anything non-trivial (it catches client/server boundary errors tsc misses — e.g. passing a Prisma Decimal to a client component).
Commit. If you're Claude, end the message with the Co-Authored-By: trailer.

How to deploy (two ways)

Preferred — in-app, no SSH: push, then an admin clicks Settings → Updates → Pull & rebuild in the live app. A privileged updater sidecar runs git pull && docker compose up -d --build app detached and the UI reloads.

git push origin master
# then click "Pull & rebuild" in the app

Manual — needs SSH to the NAS:

git push origin master
ssh root@192.168.0.5 'cd /mnt/user/appdata/moonbase && git pull && docker compose up -d --build'

Confirm success: the footer version chip (or GET /api/version) should show the version you just shipped.

Secrets — never commit them

NEXTAUTH_SECRET, GITEA_TOKEN, UPDATER_SECRET live in a gitignored host .env next to the compose file on the NAS, interpolated into compose as ${VAR}. They are not in the repo. Don't add them.

Gotchas

Don't let npx prisma resolve at runtime. With no local prisma on PATH it pulls Prisma 7, which rejects url in the datasource. The Docker image ships the full node_modules so the pinned prisma stays on PATH.
Migrations run on container start (entrypoint waits for Postgres first). A bad migration blocks startup — always test migrate deploy locally first.
First deploy of a big migration: take a backup first (Settings → Backup & Restore → Download) — the data is live (Bonna's garden).
Two people may be committing. If you didn't write a file, don't sweep it into your commit — stage only your own paths (git add <paths>) and check git status before committing.

That's the whole story: edit locally → bump version → commit → push → pull/rebuild on the NAS. Never rsync.

3.5 KiB Raw Blame History