jason/fabdash
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Add files via upload

Browse Source
This commit is contained in:
jasonMPM
2026-03-05 12:20:22 -06:00
committed by GitHub
parent b108fd8f7a
commit 429cc11ce8
1 changed files with 169 additions and 137 deletions
Download Patch File Download Diff File Expand all files Collapse all files

306
README.md
View File

@@ -16,8 +16,8 @@
- [Project Structure](#project-structure)
- [Features](#features)
- [API Reference](#api-reference)
- [Docker Deployment](#docker-deployment)
- [Unraid Installation](#unraid-installation)
- [Updating FabDash on Unraid](#updating-fabdash-on-unraid)
- [Local Development](#local-development)
- [Environment Variables](#environment-variables)
- [Database Schema](#database-schema)
@@ -27,7 +27,7 @@
## Overview
FabDash is a self-hosted project management dashboard built for fabrication teams. It features a large interactive calendar, multi-deliverable project tracking, drag-and-drop scheduling, and a per-project timeline Focus View. All wrapped in a dark/gold UI and deployed as a single Docker container.
FabDash is a self-hosted project management dashboard built for fabrication teams. It features a large interactive calendar, multi-deliverable project tracking, drag-and-drop scheduling, and a per-project timeline Focus View — all wrapped in a dark/gold UI and deployed as a single Docker container.
---
@@ -37,7 +37,7 @@ FabDash is a self-hosted project management dashboard built for fabrication team
|---|---|
| Frontend | React 18, Vite, Tailwind CSS |
| Calendar | FullCalendar v6 (daygrid, timegrid, interaction) |
| Focus View | Custom horizontal timeline with react-chrono |
| Focus View | Custom horizontal timeline (react-chrono) |
| State | Zustand |
| HTTP | Axios |
| Backend | Flask 3, Flask-SQLAlchemy, Flask-Migrate, Flask-CORS |
@@ -115,12 +115,12 @@ fabdash/
- **Large calendar view** — Month, Week, and Day modes via FullCalendar
- **Drag-and-drop** — Move deliverables to new dates; backend updates instantly
- **Multi-deliverable projects** — Add unlimited deliverables per project, each with its own due date and status
- **Color-coded projects** — 12-swatch palette + custom hex; colors appear on calendar events and sidebar cards
- **Deliverable Focus View** — Click any calendar event to open a slide-up drawer showing the full project timeline, with the selected deliverable highlighted in gold
- **Status tracking** — Upcoming / In Progress / Completed / Overdue badges per deliverable
- **Dark/gold theme** — Dark surfaces with gold as the primary accent throughout
- **Full persistence** — SQLite database via Flask-SQLAlchemy, mounted as a Docker volume
- **Multi-deliverable projects** — Unlimited deliverables per project, each with its own due date and status
- **Color-coded projects** — 12-swatch palette + custom hex input
- **Deliverable Focus View** — Click any calendar event to open a slide-up drawer with the full project timeline; clicked deliverable highlighted in gold
- **Status tracking** — Upcoming / In Progress / Completed / Overdue badges
- **Dark/gold theme** — Dark surfaces throughout with gold as the primary accent
- **Full persistence** — SQLite via Flask-SQLAlchemy, mounted as a Docker volume
---
@@ -131,7 +131,7 @@ fabdash/
| Method | Endpoint | Description |
|---|---|---|
| `GET` | `/api/projects` | List all projects with nested deliverables |
| `POST` | `/api/projects` | Create project (with optional deliverables inline) |
| `POST` | `/api/projects` | Create project (with optional inline deliverables) |
| `GET` | `/api/projects/:id` | Get single project |
| `PATCH` | `/api/projects/:id` | Update name, color, or description |
| `DELETE` | `/api/projects/:id` | Delete project + cascade deliverables |
@@ -147,49 +147,27 @@ fabdash/
---
## Docker Deployment
FabDash uses a **multi-stage Docker build**:
1. Stage 1 compiles the React/Vite frontend into static files
2. Stage 2 copies those files into Flask's `static/` folder
3. Gunicorn serves the Flask API at `/api/*` and the React SPA at `/*`
No Nginx, no separate containers, no reverse proxy required.
```bash
git clone https://github.com/yourname/fabdash.git
cd fabdash
cp .env.example .env
# Edit .env and set a strong SECRET_KEY
docker compose up -d --build
# App available at http://your-host:8080
```
---
## Unraid Installation
FabDash is designed to run cleanly on Unraid via a Docker Compose build from source.
Two methods are provided below — **Terminal (recommended)** and **Unraid Docker GUI**.
FabDash is installed by cloning the repo and building the Docker image locally on your Unraid server via SSH, then registering and managing the container through the Unraid Docker GUI. This gives you full GUI control (start, stop, logs, edit) while keeping the image local.
---
### Method 1 — Terminal via SSH (Recommended)
### Step 1 — Enable SSH on Unraid
This method builds the image directly on your Unraid server and uses `docker compose` to manage the container.
Go to **Settings → Management Access** and confirm SSH is enabled. Note your Unraid server's local IP address (visible on the Unraid dashboard header).
#### Step 1 — Enable SSH on Unraid
---
Go to **Settings → Management Access → SSH** and ensure SSH is enabled.
### Step 2 — SSH into Unraid and Clone the Repo
#### Step 2 — SSH into your Unraid server
Open a terminal on your local machine and connect:
```bash
ssh root@YOUR_UNRAID_IP
```
#### Step 3 — Clone the repository
Clone FabDash into your appdata share:
```bash
cd /mnt/user/appdata
@@ -197,140 +175,197 @@ git clone https://github.com/yourname/fabdash.git
cd fabdash
```
#### Step 4 — Create your environment file
---
### Step 3 — Build the Docker Image Locally
This command builds the image on your Unraid server and tags it as `fabdash:latest`.
The first build takes 3–5 minutes (downloads Node + Python layers, compiles React).
```bash
cp .env.example .env
nano .env
docker build -t fabdash:latest .
```
Set a strong `SECRET_KEY`:
```env
SECRET_KEY=your-strong-random-secret-key-here
FLASK_ENV=production
DATABASE_URL=sqlite:////app/data/fabdash.db
```
Press `Ctrl+X`, then `Y` to save.
#### Step 5 — Build and start the container
When complete, verify the image exists:
```bash
docker compose up -d --build
```
The build will take 2–4 minutes the first time (downloading Node and Python layers, compiling the React app).
#### Step 6 — Access FabDash
Open your browser and navigate to:
```
http://YOUR_UNRAID_IP:8080
```
#### Useful Commands
```bash
# View live logs
docker compose logs -f fabdash
# Stop the container
docker compose down
# Rebuild after a git pull (update)
git pull
docker compose up -d --build
# Open a shell inside the container
docker exec -it fabdash bash
# Run database migrations (after schema changes)
docker exec -it fabdash flask db upgrade
docker images | grep fabdash
# fabdash latest abc123def456 1 minute ago ...
```
---
### Method 2 — Unraid Docker GUI (Manual Container)
### Step 4 — Create the Data Directory
Use this method if you have already built and pushed the FabDash image to a registry (Docker Hub or GHCR). If you are running from source, use Method 1.
#### Step 1 — Push image to a registry (on your dev machine)
Create the persistent directory where SQLite will store your database:
```bash
docker build -t yourdockerhubuser/fabdash:latest .
docker push yourdockerhubuser/fabdash:latest
mkdir -p /mnt/user/appdata/fabdash/data
```
#### Step 2 — Add container via Unraid Docker tab
---
1. In Unraid, go to the **Docker** tab
2. Click **Add Container**
3. Switch to **Advanced View** (toggle top-right)
### Step 5 — Add the Container via Unraid Docker GUI
Fill in the fields:
1. In the Unraid web UI, go to the **Docker** tab
2. At the bottom, click **Add Container**
3. In the top-right of the form, toggle to **Advanced View**
Fill in the fields exactly as follows:
#### Basic Settings
| Field | Value |
|---|---|
| **Name** | `fabdash` |
| **Repository** | `yourdockerhubuser/fabdash:latest` |
| **Network Type** | Bridge |
| **Port** | Host: `8080` → Container: `8080` (TCP) |
| **Path** | Host: `/mnt/user/appdata/fabdash/data` → Container: `/app/data` |
| **Repository** | `fabdash:latest` |
| **Docker Hub URL** | *(leave blank — local image)* |
| **Network Type** | `Bridge` |
| **Console shell command** | `bash` |
| **Privileged** | `Off` |
#### Step 3 — Add Environment Variables
#### Port Mapping
Click **Add another Path, Port, Variable...** and add:
Click **Add another Path, Port, Variable, Label or Device** → select **Port**:
| Key | Value |
| Field | Value |
|---|---|
| `SECRET_KEY` | `your-strong-random-key` |
| `FLASK_ENV` | `production` |
| `DATABASE_URL` | `sqlite:////app/data/fabdash.db` |
| **Name** | `Web UI` |
| **Container Port** | `8080` |
| **Host Port** | `8080` |
| **Connection Type** | `TCP` |
#### Step 4 — Apply
> Access FabDash at `http://YOUR_UNRAID_IP:8080` after starting the container.
> Change Host Port if `8080` is already in use on your server.
Click **Apply**. Unraid will pull the image and start the container. Access at:
#### Volume / Path Mapping
Click **Add another Path, Port, Variable, Label or Device** → select **Path**:
| Field | Value |
|---|---|
| **Name** | `AppData` |
| **Container Path** | `/app/data` |
| **Host Path** | `/mnt/user/appdata/fabdash/data` |
| **Access Mode** | `Read/Write` |
> This is where `fabdash.db` will live. Data persists across all container restarts and rebuilds.
#### Environment Variables
Click **Add another Path, Port, Variable, Label or Device** → select **Variable** for each:
| Name | Key | Value |
|---|---|---|
| Secret Key | `SECRET_KEY` | `your-strong-random-secret-key-here` |
| Flask Environment | `FLASK_ENV` | `production` |
| Database URL | `DATABASE_URL` | `sqlite:////app/data/fabdash.db` |
> **SECRET_KEY** — Use a long random string. Generate one with:
> ```bash
> cat /dev/urandom | tr -dc 'a-zA-Z0-9' | fold -w 48 | head -n 1
> ```
#### Extra Parameters (optional)
| Field | Value |
|---|---|
| **Extra Parameters** | `--restart unless-stopped` |
---
### Step 6 — Apply and Start
Click **Apply** at the bottom of the form. Unraid will register and start the container using your locally built image.
Navigate to the **Docker** tab — you should see `fabdash` running with a green indicator.
Open your browser:
```
http://YOUR_UNRAID_IP:8080
```
#### Updating the Container (GUI method)
---
1. SSH into Unraid
2. Run: `docker pull yourdockerhubuser/fabdash:latest`
3. In the Docker tab, click the FabDash container icon → **Update**
### Step 7 — Verify (Optional)
Check container logs from the Unraid Docker tab by clicking the `fabdash` container icon → **Logs**, or via SSH:
```bash
docker logs fabdash --tail 50
```
A healthy startup looks like:
```
[INFO] Starting gunicorn 23.0.0
[INFO] Listening at: http://0.0.0.0:8080
[INFO] Worker booting (pid: ...)
```
---
### Data Persistence on Unraid
## Updating FabDash on Unraid
Your SQLite database is stored at:
When a new version is pushed to GitHub, update FabDash in three steps:
### Step 1 — Pull the latest code and rebuild
SSH into Unraid:
```bash
ssh root@YOUR_UNRAID_IP
cd /mnt/user/appdata/fabdash
git pull
docker build -t fabdash:latest .
```
### Step 2 — Restart the container via Unraid GUI
1. Go to the **Docker** tab in Unraid
2. Click the `fabdash` container icon
3. Select **Restart**
The container will stop, reload with the newly built image, and come back up. Your database is untouched.
### Step 3 — Verify
```bash
docker logs fabdash --tail 20
```
---
## Data Backup
Your database lives at:
```
/mnt/user/appdata/fabdash/data/fabdash.db
```
This path survives container restarts, image rebuilds, and Unraid reboots. Back it up with Unraid's **Appdata Backup** plugin or manually:
**Manual backup:**
```bash
cp /mnt/user/appdata/fabdash/data/fabdash.db /mnt/user/backups/fabdash-$(date +%Y%m%d).db
cp /mnt/user/appdata/fabdash/data/fabdash.db \
/mnt/user/backups/fabdash-$(date +%Y%m%d-%H%M).db
```
**Automated backup** — Use the **Appdata Backup/Restore** plugin from Unraid Community Applications to schedule regular backups of `/mnt/user/appdata/fabdash/`.
---
## Local Development
Run backend and frontend separately to get Vite hot-module reloading:
Run backend and frontend separately for Vite hot-module reloading:
**Terminal 1 — Flask:**
```bash
cd backend
python -m venv venv
source venv/bin/activate # Windows: venv\Scripts\activate
source venv/bin/activate # Windows: venv\Scripts\activate
pip install -r requirements.txt
export FLASK_ENV=development
flask run --port 5000
@@ -341,20 +376,20 @@ flask run --port 5000
```bash
cd frontend
npm install
npm run dev # http://localhost:5173
npm run dev # http://localhost:5173
```
Vite proxies `/api/*` calls to Flask on port 5000 automatically via `vite.config.js`.
Vite proxies all `/api/*` calls to Flask on port 5000 automatically via `vite.config.js`. No CORS issues in dev.
---
## Environment Variables
| Variable | Default | Description |
|---|---|---|
| `SECRET_KEY` | *(required)* | Flask session secret — use a long random string |
| `FLASK_ENV` | `production` | Set to `development` for debug mode |
| `DATABASE_URL` | `sqlite:////app/data/fabdash.db` | Full SQLite path (4 slashes = absolute path) |
| Variable | Required | Default | Description |
|---|---|---|---|
| `SECRET_KEY` | Yes | — | Flask session secret. Use a long random string |
| `FLASK_ENV` | No | `production` | Set to `development` for debug mode |
| `DATABASE_URL` | No | `sqlite:////app/data/fabdash.db` | SQLite path (4 slashes = absolute path) |
---
@@ -394,19 +429,19 @@ CREATE INDEX idx_deliverables_due_date ON deliverables(due_date);
- [x] Drag-and-drop deliverable rescheduling
- [x] Multi-deliverable project creation with inline rows
- [x] Add / Edit / Delete for projects and deliverables
- [x] Deliverable Focus View (slide-up drawer + horizontal timeline)
- [x] Deliverable Focus View — slide-up drawer with horizontal timeline
- [x] Active deliverable gold highlight in Focus View
- [x] Status badges (Upcoming / In Progress / Completed / Overdue)
- [x] Flask REST API + SQLite persistence
- [x] Cascade delete (project → deliverables)
- [x] Single Docker container deployment
- [x] Unraid installation guide (Terminal + GUI)
- [x] Unraid installation — local build + Docker GUI management
### v1.1 — Polish & UX
- [ ] Keyboard shortcuts (`N` = new project, `Esc` = close, arrow keys = calendar nav)
- [ ] 30-second undo toast for drag-and-drop moves
- [ ] Animated modal/drawer enter and exit transitions
- [ ] Animated modal/drawer transitions
- [ ] Hover tooltip on calendar events (preview without opening Focus View)
- [ ] Responsive layout with collapsible sidebar
- [ ] Empty state illustrations
@@ -414,7 +449,6 @@ CREATE INDEX idx_deliverables_due_date ON deliverables(due_date);
### v1.2 — Calendar Enhancements
- [ ] Agenda sidebar showing all upcoming deliverables across projects
- [ ] Click empty date → pre-filled Add Deliverable modal with project selector
- [ ] Date range selection for bulk deliverable creation
- [ ] "Today" jump button
- [ ] Week numbers in calendar header
@@ -424,30 +458,28 @@ CREATE INDEX idx_deliverables_due_date ON deliverables(due_date);
- [ ] User login (Flask-Login + JWT)
- [ ] Multi-user support with project ownership
- [ ] Role-based access per project (Owner / Editor / Viewer)
- [ ] Activity log per project
- [ ] Comment threads on deliverables
- [ ] Activity log and comment threads per deliverable
### v2.1 — Notifications & Integrations
- [ ] In-app notification center for approaching due dates
- [ ] Email reminders at configurable intervals (Flask-Mail)
- [ ] iCal / Google Calendar export per project
- [ ] iCal / Google Calendar export
- [ ] Slack webhook for deliverable status changes
- [ ] CSV import/export for bulk setup
- [ ] CSV import/export
### v2.2 — Advanced Views
- [ ] Gantt view alternate layout
- [ ] Kanban board (columns by status)
- [ ] Cross-project timeline view
- [ ] Workload heatmap showing deliverable density per day
- [ ] Archived projects with searchable history
- [ ] Workload heatmap
### v3.0 — Intelligence Layer
- [ ] AI scheduling suggestions based on project cadence
- [ ] Conflict detection — flag overloaded days
- [ ] Natural language input ("Add final draft due next Friday to CODA")
- [ ] AI scheduling suggestions
- [ ] Conflict detection for overloaded days
- [ ] Natural language deliverable input
---