i-want-to-heal-mmo/DEPLOYMENT.md

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

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:

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:

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:

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:

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:

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:

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:

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.