# CPAS Violation Tracker — Unraid Installation Guide

> **Applies to:** Unraid 6.12+ | Single container | Port 3001
> **Host requirement:** Docker Desktop only — no Node.js needed

---

## Overview

The Docker image is fully self-contained. All dependencies and the compiled
React frontend are baked in during the build. You only need Docker Desktop
on your local machine to build and export the image.

---

## Part 1 — Build the Docker Image Locally

Open a terminal in the unzipped project folder:

```bash
docker build -t cpas-tracker .
```

This single command:
- Installs backend (Node/Express) dependencies
- Installs frontend (React/Vite) dependencies
- Compiles the React app
- Packages everything into one lean image

No npm, no Node.js required on your machine beyond Docker.

---

## Part 2 — Export the Image

```bash
docker save cpas-tracker | gzip > cpas-tracker.tar.gz
```

---

## Part 3 — Transfer to Unraid

### Option A — Windows SMB (Recommended, no terminal)
1. Open File Explorer → address bar → `\\[YOUR-UNRAID-IP]`
2. Open the **appdata** share
3. Create a folder named `cpas`
4. Drag `cpas-tracker.tar.gz` into `\\[YOUR-UNRAID-IP]\appdata\cpas\`

### Option B — SCP (Mac/Linux)
```bash
scp cpas-tracker.tar.gz root@[YOUR-UNRAID-IP]:/mnt/user/appdata/cpas/
```

---

## Part 4 — Prepare Unraid (Terminal — one time only)

1. In Unraid GUI → **Tools** → **Terminal**
2. Run:

```bash
mkdir -p /mnt/user/appdata/cpas/db
docker load < /mnt/user/appdata/cpas/cpas-tracker.tar.gz
```

Expected output:
```
Loaded image: cpas-tracker:latest
```

3. Close the terminal — no further terminal use needed for normal operation.

---

## Part 5 — Add the Container in Unraid GUI

### 5.1 Navigate to Docker tab
1. Click **Docker** in the top nav
2. Confirm Docker is **Enabled** (green toggle)
3. Scroll to bottom → click **Add Container**
4. Toggle **Advanced View ON** (top-right of the form)

---

### 5.2 Basic Settings

| Field | Value |
|---|---|
| **Name** | `cpas-tracker` |
| **Repository** | `cpas-tracker` |
| **Docker Hub URL** | *(leave blank — local image)* |
| **WebUI** | `http://[IP]:[PORT:3001]` |
| **Network Type** | `Bridge` |
| **Privileged** | `Off` |
| **Restart Policy** | `Unless Stopped` |
| **Console shell** | `bash` |

> Setting the WebUI field enables a one-click launch icon on the Docker tab.

---

### 5.3 Port Mapping

Click **Add another Path, Port, Variable, Label or Device**

| Setting | Value |
|---|---|
| Config Type | `Port` |
| Name | `Web UI` |
| Container Port | `3001` |
| Host Port | `3001` |
| Protocol | `TCP` |

---

### 5.4 Volume Mapping (Database Persistence)

Click **Add another Path, Port, Variable, Label or Device**

| Setting | Value |
|---|---|
| Config Type | `Path` |
| Name | `Database` |
| Container Path | `/data` |
| Host Path | `/mnt/user/appdata/cpas/db` |
| Access Mode | `Read/Write` |

> The SQLite database lives here and survives container restarts and image updates.

---

### 5.5 Environment Variables

Click **Add another Path, Port, Variable, Label or Device** for each:

**Variable 1 — Port**

| Setting | Value |
|---|---|
| Config Type | `Variable` |
| Name | `Port` |
| Key | `PORT` |
| Value | `3001` |

**Variable 2 — Database Path**

| Setting | Value |
|---|---|
| Config Type | `Variable` |
| Name | `Database Path` |
| Key | `DB_PATH` |
| Value | `/data/cpas.db` |

---

### 5.6 Apply

1. Click **Apply** at the bottom
2. Watch the progress log — wait for "Container started"
3. Click **Done**

---

## Part 6 — Verify

1. Docker tab → **cpas-tracker** should show a green icon
2. Click the container icon → **WebUI**
   Or open: `http://[YOUR-UNRAID-IP]:3001`
3. Confirm **● API connected** appears in the header
4. Health check: `http://[YOUR-UNRAID-IP]:3001/api/health`
   → `{"status":"ok","timestamp":"..."}`

---

## Part 7 — Updating After Code Changes

### Locally:
```bash
docker build -t cpas-tracker .
docker save cpas-tracker | gzip > cpas-tracker.tar.gz
```

### Transfer to Unraid (same as Part 3)

### On Unraid — GUI only after first load:
1. Copy new tar.gz to Unraid (SMB drag-and-drop)
2. **Tools → Terminal** → `docker load < /mnt/user/appdata/cpas/cpas-tracker.tar.gz`
3. **Docker tab** → click `cpas-tracker` icon → **Restart**

> Your database at `/mnt/user/appdata/cpas/db/cpas.db` is never touched during updates.

---

## Troubleshooting

| Problem | Fix |
|---|---|
| Container won't start | Docker tab → container icon → **Logs** |
| Port 3001 conflict | Change Host Port to `3002` in Edit Container |
| "API unreachable" in UI | Confirm green icon, check Logs, try Restart |
| DB permission error | Terminal: `chmod 755 /mnt/user/appdata/cpas/db` |
| Inspect DB directly | Terminal: `docker exec -it cpas-tracker sh` then `sqlite3 /data/cpas.db ".tables"` |

---

## Quick Reference — Unraid Docker Tab Actions

| Action | Steps |
|---|---|
| Open app | Container icon → WebUI |
| View logs | Container icon → Logs |
| Restart | Container icon → Restart |
| Edit settings | Container icon → Edit |
| Stop/Start | Container icon → Stop / Start |

---

*CPAS Violation Tracker — Phase 1 | Message Point Media internal use*