# TrueNAS deployment

This game uses the same proven local-Gitea pattern as `testgame`: clone from the
Gitea bare repository on the TrueNAS filesystem, mount that working checkout
into one Node container, and update it with a local Git pull plus app restart.

## What the TrueNAS server does

The `iwanttoheal-mmo` TrueNAS app is the game's live online server. One Node
process serves the browser bundle and authenticated `/api` routes on port `4173`.
The reverse proxy exposes both at `https://iwanttoheal.phenomrom.com`.

SQLite persists accounts, sessions, cloud saves, boss-kill rankings, and
roguelike records under `/app/data/game.db`. The separate data mount survives
container replacement. TrueNAS Gitea remains the source repository used for
deployment; it is not the game database.

## Paths

```text
Local Gitea bare repository:
/mnt/.ix-apps/app_mounts/gitea/data/git/repositories/phenom/i-want-to-heal-mmo.git

Runnable working checkout:
/mnt/usbssds/apps/iwanttoheal-mmo/app

Persistent game data:
/mnt/usbssds/apps/iwanttoheal-mmo/data

Public URL:
https://iwanttoheal.phenomrom.com

Container/host port:
4173
```

The bare Gitea repository is not a runnable application directory. Use a local
`git clone`; do not copy the bare repository with `cp`. Local clone/pull keeps
the source transfer on TrueNAS and creates the working tree the container needs.

## First installation

This configuration uses a separate `iwanttoheal-mmo` working directory, so it
does not modify the old app checkout or its data.

Confirm the new repository path. If the first command fails, use the search:

```sh
sudo test -d /mnt/.ix-apps/app_mounts/gitea/data/git/repositories/phenom/i-want-to-heal-mmo.git
sudo find /mnt -type d -name "i-want-to-heal-mmo.git" -prune -print 2>/dev/null
```

Clone entirely through the local filesystem:

```sh
sudo mkdir -p /mnt/usbssds/apps/iwanttoheal-mmo/{app,data}
sudo git config --global --add safe.directory \
  /mnt/.ix-apps/app_mounts/gitea/data/git/repositories/phenom/i-want-to-heal-mmo.git
sudo git clone \
  /mnt/.ix-apps/app_mounts/gitea/data/git/repositories/phenom/i-want-to-heal-mmo.git \
  /mnt/usbssds/apps/iwanttoheal-mmo/app
sudo chown -R truenas_admin:truenas_admin /mnt/usbssds/apps/iwanttoheal-mmo
```

Verify the checkout:

```sh
git -C /mnt/usbssds/apps/iwanttoheal-mmo/app remote -v
git -C /mnt/usbssds/apps/iwanttoheal-mmo/app branch --show-current
ls /mnt/usbssds/apps/iwanttoheal-mmo/app/package.json
```

Expected branch: `main`. Expected origin: local Gitea path above.

## Install as a TrueNAS app

1. Open **Apps**.
2. Open **Discover**.
3. Open the three-dot menu.
4. Select **Install via YAML**.
5. Name the app `iwanttoheal-mmo`.
6. Paste:

```yaml
services:
  iwanttoheal:
    image: node:24-bookworm-slim
    command: >-
      sh -lc "corepack pnpm install --frozen-lockfile && corepack pnpm run db:init && corepack pnpm run build && corepack pnpm start"
    environment:
      CORS_ORIGINS: "https://iwanttoheal.phenomrom.com,capacitor://localhost,http://localhost"
      DATA_DIR: /app/data
      HOST: 0.0.0.0
      PORT: "4173"
    init: true
    ports:
      - "4173:4173"
    restart: unless-stopped
    volumes:
      - /mnt/usbssds/apps/iwanttoheal-mmo/app:/app
      - /mnt/usbssds/apps/iwanttoheal-mmo/data:/app/data
    working_dir: /app
```

Do not remove the `/app/data` mount or place the SQLite database inside the source
checkout. Back up `/mnt/usbssds/apps/iwanttoheal-mmo/data/game.db` before database
migrations or destructive maintenance.

From the app checkout, create a consistent SQLite backup with:

```sh
DATA_DIR=/mnt/usbssds/apps/iwanttoheal-mmo/data \
BACKUP_DIR=/mnt/usbssds/apps/iwanttoheal-mmo/backups \
corepack pnpm run db:backup
```

The separate volume protects the old app files and data. The YAML still maps
host port `4173`, so the old and MMO apps cannot run simultaneously while both
use that host port. Stop the old app, or assign this app an unused host port and
separate reverse-proxy hostname.

After deployment, test from the TrueNAS shell or another LAN machine:

```sh
curl -I http://TRUENAS-IP:4173
```

Expected result: HTTP `200`. Keep the existing HTTPS reverse proxy pointed at
`TRUENAS-IP:4173` for `iwanttoheal.phenomrom.com`.

## Update workflow

Push `main` from the development Mac. Then run on TrueNAS:

```sh
git -C /mnt/usbssds/apps/iwanttoheal-mmo/app pull --ff-only \
  /mnt/.ix-apps/app_mounts/gitea/data/git/repositories/phenom/i-want-to-heal-mmo.git \
  main
```

This transfers Git objects locally from Gitea storage; it does not download the
game through HTTPS. Restart `iwanttoheal-mmo` in the TrueNAS Apps UI afterward. The
container startup command installs locked dependencies, rebuilds the browser
bundle, and starts port `4173`.

For simultaneous operation, keep the new app name/directory and also assign an
unused host port plus a separate reverse-proxy hostname.