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