tonym
b8af0f986b
- 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>
78 lines
3.5 KiB
Markdown
78 lines
3.5 KiB
Markdown
# 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
|
|
|
|
1. **Edit** code in your local working copy.
|
|
2. **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.
|
|
3. **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.
|
|
4. **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).
|
|
5. **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.
|
|
|
|
```sh
|
|
git push origin master
|
|
# then click "Pull & rebuild" in the app
|
|
```
|
|
|
|
**Manual — needs SSH to the NAS:**
|
|
|
|
```sh
|
|
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.**
|