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