init
This commit is contained in:
jason
195
UNRAID.md
Normal file
195
UNRAID.md
Normal file
@@ -0,0 +1,195 @@
|
||||
# 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`
|
||||
|
||||
Reference in New Issue
Block a user