From 7ea358e66a7f9ba09e46e4957b8ffc985456849e Mon Sep 17 00:00:00 2001 From: jason Date: Sat, 21 Mar 2026 22:09:30 -0500 Subject: [PATCH] Add UNRAID.md with GUI and CLI installation instructions - GUI method: Docker tab field-by-field walkthrough (name, port, volume, env vars) - CLI method: docker run one-liner with all required flags - Building the image: local build on Unraid terminal + push-to-registry option - JWT_SECRET generation tip using /proc/sys/kernel/random/uuid - Updating, password change, backup, and troubleshooting sections Co-Authored-By: Claude Sonnet 4.6 --- UNRAID.md | 251 ++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 251 insertions(+) create mode 100644 UNRAID.md diff --git a/UNRAID.md b/UNRAID.md new file mode 100644 index 0000000..94b4ede --- /dev/null +++ b/UNRAID.md @@ -0,0 +1,251 @@ +# RackMapper — Unraid Installation Guide + +Two methods are covered: **GUI (Community Applications / Docker template)** and **CLI**. + +--- + +## Prerequisites + +- Unraid 6.10 or later +- The RackMapper image built and available (either pushed to a registry or built locally — see [Building the Image](#building-the-image)) +- A share to store the persistent database (e.g. `/mnt/user/appdata/rackmapper`) + +--- + +## Building the Image + +RackMapper is not on Docker Hub. You must build it from source on your Unraid server or on another machine and push it to a registry (e.g. a local Gitea registry, Docker Hub private repo, or GHCR). + +### Option A — Build directly on Unraid via Unraid Terminal + +```bash +# 1. Clone the repo (or upload the source to a share) +cd /mnt/user/appdata +git clone https://github.com/YOUR_USERNAME/rack-planner rackmapper-src + +# 2. Build the image +cd /mnt/user/appdata/rackmapper-src +docker build -t rackmapper:latest . + +# 3. Verify the image exists +docker images | grep rackmapper +``` + +### Option B — Build on another machine and push to a registry + +```bash +# Build and push to Docker Hub (replace with your username) +docker build -t yourdockerhubuser/rackmapper:latest . +docker push yourdockerhubuser/rackmapper:latest +``` + +Then use `yourdockerhubuser/rackmapper:latest` as the image name in the steps below. + +--- + +## Method 1 — GUI (Docker tab) + +### Step 1 — Create the data directory + +Open the Unraid terminal (**Tools → Terminal**) and run: + +```bash +mkdir -p /mnt/user/appdata/rackmapper/data +``` + +### Step 2 — Add the container + +1. Go to the **Docker** tab +2. At the bottom, click **Add Container** +3. Fill in the fields as follows: + +--- + +#### Basic + +| Field | Value | +|---|---| +| **Name** | `rackmapper` | +| **Repository** | `rackmapper:latest` (local build) or `yourdockerhubuser/rackmapper:latest` | +| **Docker Hub URL** | *(leave blank for local image)* | +| **Network Type** | `bridge` | +| **Console shell command** | `sh` | +| **Privileged** | Off | +| **Restart Policy** | Unless stopped | + +--- + +#### Port Mapping + +Click **Add another Path, Port, Variable, Label or Device** → select **Port** + +| Field | Value | +|---|---| +| **Name** | Web UI | +| **Container Port** | `3001` | +| **Host Port** | `3001` *(change if port is taken)* | +| **Protocol** | TCP | + +--- + +#### Volume Mapping + +Click **Add another Path, Port, Variable, Label or Device** → select **Path** + +| Field | Value | +|---|---| +| **Name** | AppData | +| **Container Path** | `/app/data` | +| **Host Path** | `/mnt/user/appdata/rackmapper/data` | +| **Access Mode** | Read/Write | + +--- + +#### Environment Variables + +Click **Add another Path, Port, Variable, Label or Device** → select **Variable** for each row below: + +| Name | Key | Value | +|---|---|---| +| Node Environment | `NODE_ENV` | `production` | +| Port | `PORT` | `3001` | +| Database URL | `DATABASE_URL` | `file:./data/rackmapper.db` | +| Admin Username | `ADMIN_USERNAME` | `admin` *(or your preferred username)* | +| Admin Password | `ADMIN_PASSWORD` | `yourpassword` | +| JWT Secret | `JWT_SECRET` | `a-long-random-string-min-32-chars` | +| JWT Expiry | `JWT_EXPIRY` | `8h` *(optional — defaults to 8h)* | + +> **JWT_SECRET** should be a random string of at least 32 characters. You can generate one in the Unraid terminal: +> ```bash +> cat /proc/sys/kernel/random/uuid | tr -d '-' && cat /proc/sys/kernel/random/uuid | tr -d '-' +> ``` + +--- + +### Step 3 — Apply + +Click **Apply**. Unraid will pull/use the image and start the container. + +Open `http://YOUR-UNRAID-IP:3001` in your browser. + +--- + +## Method 2 — CLI + +### Step 1 — Create the data directory + +```bash +mkdir -p /mnt/user/appdata/rackmapper/data +``` + +### Step 2 — Run the container + +```bash +docker run -d \ + --name rackmapper \ + --restart unless-stopped \ + -p 3001:3001 \ + -v /mnt/user/appdata/rackmapper/data:/app/data \ + -e NODE_ENV=production \ + -e PORT=3001 \ + -e DATABASE_URL="file:./data/rackmapper.db" \ + -e ADMIN_USERNAME=admin \ + -e ADMIN_PASSWORD=yourpassword \ + -e JWT_SECRET=a-long-random-string-min-32-chars \ + -e JWT_EXPIRY=8h \ + rackmapper:latest +``` + +### Step 3 — Verify + +```bash +# Check container is running +docker ps | grep rackmapper + +# Tail startup logs (migrations run automatically on first start) +docker logs -f rackmapper +``` + +You should see output ending with something like: + +``` +Applied 1 migration. +Server listening on port 3001 +``` + +Open `http://YOUR-UNRAID-IP:3001` in your browser. + +--- + +## Updating + +When a new version of the source is available: + +```bash +# Rebuild the image +cd /mnt/user/appdata/rackmapper-src +git pull +docker build -t rackmapper:latest . + +# Restart the container (migrations run automatically on startup) +docker restart rackmapper +``` + +From the GUI: **Docker tab → rackmapper → Force Update** (if using a remote registry), or restart after rebuilding locally. + +--- + +## Changing the Password + +1. Go to **Docker tab → rackmapper → Edit** +2. Update the `ADMIN_PASSWORD` variable +3. Click **Apply** — Unraid will recreate the container with the new value + +Or via CLI: + +```bash +docker stop rackmapper +docker rm rackmapper +# Re-run the docker run command above with the new ADMIN_PASSWORD value +``` + +--- + +## Data & Backups + +The SQLite database file lives at: + +``` +/mnt/user/appdata/rackmapper/data/rackmapper.db +``` + +Back it up like any other appdata file — Unraid's built-in **Appdata Backup** plugin (CA Appdata Backup) will cover it automatically if your appdata share is included. + +To manually back up: + +```bash +cp /mnt/user/appdata/rackmapper/data/rackmapper.db \ + /mnt/user/backups/rackmapper-$(date +%Y%m%d).db +``` + +--- + +## Troubleshooting + +**Container exits immediately** +```bash +docker logs rackmapper +``` +Most commonly caused by a missing or malformed `JWT_SECRET` or `ADMIN_PASSWORD`. + +**Port 3001 already in use** +Change the **Host Port** to any free port (e.g. `3002`). The Container Port must stay `3001`. + +**"Server not configured: admin credentials missing" on login** +One or both of `ADMIN_USERNAME` / `ADMIN_PASSWORD` environment variables is not set. Check the container's environment in the Docker tab. + +**Database not persisting across restarts** +Verify the volume mapping — the host path `/mnt/user/appdata/rackmapper/data` must exist before starting the container and must be mapped to `/app/data` inside the container. + +**Migrations not running** +The container runs `npx prisma migrate deploy` automatically on startup. Check `docker logs rackmapper` for any migration errors.