Initial commit of Docker project
This commit is contained in:
219
README_UNRAID_INSTALL.md
Executable file
219
README_UNRAID_INSTALL.md
Executable file
@@ -0,0 +1,219 @@
|
||||
# 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*
|
||||
Reference in New Issue
Block a user