mrp/UNRAID.md

# Unraid Install Guide

## Purpose

This guide explains how to deploy MRP Codex on an Unraid server using the Unraid Docker GUI rather than command-line Docker management.

## What this container expects

- One published web port for the application
- One persistent app data path mounted to `/app/data`
- Environment variables for the server port, JWT secret, and SQLite path
- Automatic Prisma migration execution during container startup

MRP Codex stores both the SQLite database and uploaded files inside the same persistent container path:

- database: `/app/data/prisma/app.db`
- uploads: `/app/data/uploads`

## Before you start

- Build and push the image to a registry your Unraid server can access, or import it manually if you are self-hosting images
- Choose an Unraid share for persistent app data, for example:
  - `/mnt/user/appdata/mrp-codex`
- Choose the port you want to expose in Unraid, for example:
  - host port `3000`
  - container port `3000`

## Recommended Unraid paths

- App data share: `/mnt/user/appdata/mrp-codex`
- Optional backup target: `/mnt/user/backups/mrp-codex`

Keep the entire app data folder together so backups capture both the SQLite database and file attachments.

## Add the container in the Unraid GUI

### 1. Open the Docker tab

- In Unraid, go to `Docker`
- Click `Add Container`

### 2. Basic container settings

Use these values as the starting point:

- Name: `mrp-codex`
- Repository: your built image name, for example `your-registry/mrp-codex:latest`
- Network Type: `bridge`
- Console shell command: leave default
- Privileged: `Off`

### 3. Port mapping

Add a port mapping:

- Name: `WebUI`
- Container Port: `3000`
- Host Port: `3000`
- Connection Type: `TCP`

If port `3000` is already used on the Unraid host, change only the host port.

### 4. Path mapping

Add a single path mapping:

- Name: `data`
- Container Path: `/app/data`
- Host Path: `/mnt/user/appdata/mrp-codex`
- Access Mode: `Read/Write`

This is the critical mapping. Do not split the database and uploads into separate container paths unless you also update the app configuration.

### 5. Environment variables

Add these variables in the Unraid GUI:

- `NODE_ENV` = `production`
- `PORT` = `3000`
- `JWT_SECRET` = `replace-with-a-long-random-secret`
- `DATA_DIR` = `/app/data`
- `DATABASE_URL` = `file:../../data/prisma/app.db`
- `PUPPETEER_EXECUTABLE_PATH` = `/usr/bin/chromium`
- `CLIENT_ORIGIN` = `http://YOUR-UNRAID-IP:3000`

If you use a reverse proxy and external hostname, set `CLIENT_ORIGIN` to the final browser URL instead, for example:

- `CLIENT_ORIGIN` = `https://mrp.yourdomain.com`

### 6. Optional first-admin overrides

You can set the seeded admin login explicitly on first deployment:

- `ADMIN_EMAIL` = `admin@yourcompany.com`
- `ADMIN_PASSWORD` = `use-a-strong-initial-password`

If you do not set them, the defaults from the app bootstrapping logic are used.

## First start behavior

On first container start, the entrypoint will:

1. Ensure `/app/data/prisma` and `/app/data/uploads` exist
2. Run `npx prisma migrate deploy`
3. Start the Node.js server

The frontend is served by the same container as the API, so there is only one exposed web port.

## First login

If you did not override the admin credentials with environment variables, use:

- email: `admin@mrp.local`
- password: `ChangeMe123!`

Change the admin password after first login if you keep the default bootstrap user.

## Updating the container in Unraid

When you publish a new image:

1. Open the `Docker` tab
2. Apply the update from the Unraid GUI
3. Start the container

Because MRP Codex runs `prisma migrate deploy` during startup, committed migrations are applied automatically before the app launches.

This is especially important now that recent releases added CRM expansion, inventory transactions, sales and purchasing documents, shipping, packing slips, the inventory `defaultPrice` field, and purchasable-only purchase-order item selection. Let the container complete startup migrations before testing new screens.

## Backup guidance

Back up the host directory mapped to `/app/data`, typically:

- `/mnt/user/appdata/mrp-codex`

That captures:

- the SQLite database
- uploaded CAD drawings and supporting files
- logos and other persisted attachments

For consistent backups, stop the container before copying the appdata directory.

## Reverse proxy notes

If you place MRP Codex behind Nginx Proxy Manager, Traefik, or another reverse proxy:

- keep the Unraid container on `bridge` or your preferred proxy-compatible network
- point the proxy at the Unraid host IP and chosen host port
- set `CLIENT_ORIGIN` to the final external URL

## Troubleshooting

### Container starts then exits

Check the container logs in Unraid. Common causes:

- invalid `DATABASE_URL`
- missing write access to the host path mapped to `/app/data`
- bad or missing environment values

### PDFs fail to generate

The image already includes Chromium and the required runtime libraries. If PDF generation still fails:

- confirm `PUPPETEER_EXECUTABLE_PATH=/usr/bin/chromium`
- inspect the container logs for Puppeteer launch errors

### Application boots but data does not persist

Verify the `/app/data` path mapping in Unraid. If `/app/data` is not mapped to a persistent Unraid share, the database and uploads will be lost when the container is recreated.

### Browser login or CORS issues

Set `CLIENT_ORIGIN` to the exact URL used by the browser, including protocol and port.

## Suggested Unraid template summary

- Repository: `your-registry/mrp-codex:latest`
- Network Type: `bridge`
- Port: `3000` -> `3000`
- Path: `/mnt/user/appdata/mrp-codex` -> `/app/data`
- Env: `NODE_ENV=production`
- Env: `PORT=3000`
- Env: `JWT_SECRET=<strong secret>`
- Env: `DATA_DIR=/app/data`
- Env: `DATABASE_URL=file:../../data/prisma/app.db`
- Env: `PUPPETEER_EXECUTABLE_PATH=/usr/bin/chromium`
- Env: `CLIENT_ORIGIN=http://YOUR-UNRAID-IP:3000`