rack-planner/UNRAID.md

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)
• 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

# 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

# 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:

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:

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

mkdir -p /mnt/user/appdata/rackmapper/data

Step 2 — Run the container

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

# 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:

# 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:

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:

cp /mnt/user/appdata/rackmapper/data/rackmapper.db \
   /mnt/user/backups/rackmapper-$(date +%Y%m%d).db

---

Troubleshooting

Container exits immediately

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.