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](#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)* |
| 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:
> ```bash
> 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

```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 \
  -e COOKIE_SECURE=false \
  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.