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:/app/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)
Secure Cookie	COOKIE_SECURE	false (set to true only if behind HTTPS reverse proxy)

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 '-'

COOKIE_SECURE — Leave this unset or false for direct HTTP access (the default for Unraid). Only set it to true if you are terminating HTTPS at a reverse proxy (e.g. Nginx Proxy Manager, Traefik) in front of RackMapper, otherwise login will succeed but every subsequent API call will return 401 Unauthorized because the browser will refuse to send the session cookie over plain HTTP.

---

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:/app/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 \
  -e COOKIE_SECURE=false \
  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.