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

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