codexium-odoo/UNRAID.md

# Unraid Install Guide

## Documentation maintenance

- Keep [CHANGELOG.md](D:/CODING/mrp-codex/CHANGELOG.md) updated when deployment behavior, startup flow, persistence expectations, or operator-facing install steps materially change.
- If Unraid deployment guidance changes, update the companion project docs in [README.md](D:/CODING/mrp-codex/README.md), [INSTRUCTIONS.md](D:/CODING/mrp-codex/INSTRUCTIONS.md), and [ROADMAP.md](D:/CODING/mrp-codex/ROADMAP.md) in the same change set when relevant.

## Purpose

This guide explains how to deploy CODEXIUM 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

CODEXIUM 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/codexium`
- 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/codexium`
- Optional backup target: `/mnt/user/backups/codexium`

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 `/app/server/node_modules/.bin/prisma migrate deploy --schema /app/server/prisma/schema.prisma`
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 CODEXIUM 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/logistics documents, the inventory `defaultPrice` field, purchasable-only purchase-order item selection, the new projects domain, manufacturing work orders, audit tooling, and persisted auth sessions. 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 CODEXIUM 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`