cpas/README_UNRAID_INSTALL.md

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:

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

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)

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:

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:

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