mrp/UNRAID.md

Unraid Install Guide

Documentation maintenance

• Keep 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, INSTRUCTIONS.md, and ROADMAP.md in the same change set when relevant.

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/logistics documents, the inventory defaultPrice field, purchasable-only purchase-order item selection, and the new projects domain. 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