jason/rack-planner
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Add UNRAID.md with GUI and CLI installation instructions

Browse Source 
- 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 <noreply@anthropic.com>
This commit is contained in:
jason
2026-03-21 22:09:30 -05:00
parent 84cd94a0f5
commit 7ea358e66a
1 changed files with 251 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

251
UNRAID.md Normal file
View File

@@ -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.