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

Variable 3 — Admin Username

Setting	Value
Config Type	Variable
Name	Admin Username
Key	ADMIN_USERNAME
Value	admin

Variable 4 — Admin Password

Setting	Value
Config Type	Variable
Name	Admin Password
Key	ADMIN_PASSWORD
Value	(set a strong password — do not leave the default)

Important: The app requires login. The admin account is created from ADMIN_USERNAME / ADMIN_PASSWORD on every start. Always set a strong ADMIN_PASSWORD — the image ships with a placeholder (changeme) that must be overridden. To rotate the admin password later, change this value and Restart the container. Additional user accounts are created in-app by an admin (top-right Users button) and are not affected by restarts.

---

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. A login screen appears. Sign in with the ADMIN_USERNAME / ADMIN_PASSWORD you set in step 5.5.
4. Confirm ● API connected appears in the header
5. Health check (no login required): 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
Can't log in / forgot admin password	Edit Container → set a new ADMIN_PASSWORD → Restart. The admin password re-syncs from this variable on every start.
"ADMIN_PASSWORD not set" in logs	Add the ADMIN_PASSWORD variable (step 5.5) and restart — without it the admin account is not created.
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