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

302
README.md
View File

@@ -16,8 +16,8 @@
- [Project Structure](#project-structure) - [Project Structure](#project-structure)
- [Features](#features) - [Features](#features)
- [API Reference](#api-reference) - [API Reference](#api-reference)
- [Docker Deployment](#docker-deployment)
- [Unraid Installation](#unraid-installation) - [Unraid Installation](#unraid-installation)
- [Updating FabDash on Unraid](#updating-fabdash-on-unraid)
- [Local Development](#local-development) - [Local Development](#local-development)
- [Environment Variables](#environment-variables) - [Environment Variables](#environment-variables)
- [Database Schema](#database-schema) - [Database Schema](#database-schema)
@@ -27,7 +27,7 @@
## Overview ## 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 | | Frontend | React 18, Vite, Tailwind CSS |
| Calendar | FullCalendar v6 (daygrid, timegrid, interaction) | | Calendar | FullCalendar v6 (daygrid, timegrid, interaction) |
| Focus View | Custom horizontal timeline with react-chrono | | Focus View | Custom horizontal timeline (react-chrono) |
| State | Zustand | | State | Zustand |
| HTTP | Axios | | HTTP | Axios |
| Backend | Flask 3, Flask-SQLAlchemy, Flask-Migrate, Flask-CORS | | Backend | Flask 3, Flask-SQLAlchemy, Flask-Migrate, Flask-CORS |
@@ -115,12 +115,12 @@ fabdash/
- **Large calendar view** — Month, Week, and Day modes via FullCalendar - **Large calendar view** — Month, Week, and Day modes via FullCalendar
- **Drag-and-drop** — Move deliverables to new dates; backend updates instantly - **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 - **Multi-deliverable projects** — 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 - **Color-coded projects** — 12-swatch palette + custom hex input
- **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 - **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 per deliverable - **Status tracking** — Upcoming / In Progress / Completed / Overdue badges
- **Dark/gold theme** — Dark surfaces with gold as the primary accent throughout - **Dark/gold theme** — Dark surfaces throughout with gold as the primary accent
- **Full persistence** — SQLite database via Flask-SQLAlchemy, mounted as a Docker volume - **Full persistence** — SQLite via Flask-SQLAlchemy, mounted as a Docker volume
--- ---
@@ -131,7 +131,7 @@ fabdash/
| Method | Endpoint | Description | | Method | Endpoint | Description |
|---|---|---| |---|---|---|
| `GET` | `/api/projects` | List all projects with nested deliverables | | `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 | | `GET` | `/api/projects/:id` | Get single project |
| `PATCH` | `/api/projects/:id` | Update name, color, or description | | `PATCH` | `/api/projects/:id` | Update name, color, or description |
| `DELETE` | `/api/projects/:id` | Delete project + cascade deliverables | | `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 ## Unraid Installation
FabDash is designed to run cleanly on Unraid via a Docker Compose build from source. 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.
Two methods are provided below — **Terminal (recommended)** and **Unraid Docker GUI**.
--- ---
### 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 ```bash
ssh root@YOUR_UNRAID_IP ssh root@YOUR_UNRAID_IP
``` ```
#### Step 3 — Clone the repository Clone FabDash into your appdata share:
```bash ```bash
cd /mnt/user/appdata cd /mnt/user/appdata
@@ -197,133 +175,190 @@ git clone https://github.com/yourname/fabdash.git
cd fabdash 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 ```bash
cp .env.example .env docker build -t fabdash:latest .
nano .env
``` ```
Set a strong `SECRET_KEY`: When complete, verify the image exists:
```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
```bash ```bash
docker compose up -d --build docker images | grep fabdash
``` # fabdash latest abc123def456 1 minute ago ...
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
``` ```
--- ---
### 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. Create the persistent directory where SQLite will store your database:
#### Step 1 — Push image to a registry (on your dev machine)
```bash ```bash
docker build -t yourdockerhubuser/fabdash:latest . mkdir -p /mnt/user/appdata/fabdash/data
docker push yourdockerhubuser/fabdash:latest
``` ```
#### Step 2 — Add container via Unraid Docker tab ---
1. In Unraid, go to the **Docker** tab ### Step 5 — Add the Container via Unraid Docker GUI
2. Click **Add Container**
3. Switch to **Advanced View** (toggle top-right)
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 | | Field | Value |
|---|---| |---|---|
| **Name** | `fabdash` | | **Name** | `fabdash` |
| **Repository** | `yourdockerhubuser/fabdash:latest` | | **Repository** | `fabdash:latest` |
| **Network Type** | Bridge | | **Docker Hub URL** | *(leave blank — local image)* |
| **Port** | Host: `8080` → Container: `8080` (TCP) | | **Network Type** | `Bridge` |
| **Path** | Host: `/mnt/user/appdata/fabdash/data` → Container: `/app/data` | | **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` | | **Name** | `Web UI` |
| `FLASK_ENV` | `production` | | **Container Port** | `8080` |
| `DATABASE_URL` | `sqlite:////app/data/fabdash.db` | | **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 http://YOUR_UNRAID_IP:8080
``` ```
#### Updating the Container (GUI method) ---
1. SSH into Unraid ### Step 7 — Verify (Optional)
2. Run: `docker pull yourdockerhubuser/fabdash:latest`
3. In the Docker tab, click the FabDash container icon → **Update** 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 /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 ```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 ## 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:** **Terminal 1 — Flask:**
@@ -344,17 +379,17 @@ 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 ## Environment Variables
| Variable | Default | Description | | Variable | Required | Default | Description |
|---|---|---| |---|---|---|---|
| `SECRET_KEY` | *(required)* | Flask session secret — use a long random string | | `SECRET_KEY` | Yes | — | Flask session secret. Use a long random string |
| `FLASK_ENV` | `production` | Set to `development` for debug mode | | `FLASK_ENV` | No | `production` | Set to `development` for debug mode |
| `DATABASE_URL` | `sqlite:////app/data/fabdash.db` | Full SQLite path (4 slashes = absolute path) | | `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] Drag-and-drop deliverable rescheduling
- [x] Multi-deliverable project creation with inline rows - [x] Multi-deliverable project creation with inline rows
- [x] Add / Edit / Delete for projects and deliverables - [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] Active deliverable gold highlight in Focus View
- [x] Status badges (Upcoming / In Progress / Completed / Overdue) - [x] Status badges (Upcoming / In Progress / Completed / Overdue)
- [x] Flask REST API + SQLite persistence - [x] Flask REST API + SQLite persistence
- [x] Cascade delete (project → deliverables) - [x] Cascade delete (project → deliverables)
- [x] Single Docker container deployment - [x] Single Docker container deployment
- [x] Unraid installation guide (Terminal + GUI) - [x] Unraid installation — local build + Docker GUI management
### v1.1 — Polish & UX ### v1.1 — Polish & UX
- [ ] Keyboard shortcuts (`N` = new project, `Esc` = close, arrow keys = calendar nav) - [ ] Keyboard shortcuts (`N` = new project, `Esc` = close, arrow keys = calendar nav)
- [ ] 30-second undo toast for drag-and-drop moves - [ ] 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) - [ ] Hover tooltip on calendar events (preview without opening Focus View)
- [ ] Responsive layout with collapsible sidebar - [ ] Responsive layout with collapsible sidebar
- [ ] Empty state illustrations - [ ] Empty state illustrations
@@ -414,7 +449,6 @@ CREATE INDEX idx_deliverables_due_date ON deliverables(due_date);
### v1.2 — Calendar Enhancements ### v1.2 — Calendar Enhancements
- [ ] Agenda sidebar showing all upcoming deliverables across projects - [ ] 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 - [ ] Date range selection for bulk deliverable creation
- [ ] "Today" jump button - [ ] "Today" jump button
- [ ] Week numbers in calendar header - [ ] Week numbers in calendar header
@@ -424,30 +458,28 @@ CREATE INDEX idx_deliverables_due_date ON deliverables(due_date);
- [ ] User login (Flask-Login + JWT) - [ ] User login (Flask-Login + JWT)
- [ ] Multi-user support with project ownership - [ ] Multi-user support with project ownership
- [ ] Role-based access per project (Owner / Editor / Viewer) - [ ] Role-based access per project (Owner / Editor / Viewer)
- [ ] Activity log per project - [ ] Activity log and comment threads per deliverable
- [ ] Comment threads on deliverables
### v2.1 — Notifications & Integrations ### v2.1 — Notifications & Integrations
- [ ] In-app notification center for approaching due dates - [ ] In-app notification center for approaching due dates
- [ ] Email reminders at configurable intervals (Flask-Mail) - [ ] Email reminders at configurable intervals (Flask-Mail)
- [ ] iCal / Google Calendar export per project - [ ] iCal / Google Calendar export
- [ ] Slack webhook for deliverable status changes - [ ] Slack webhook for deliverable status changes
- [ ] CSV import/export for bulk setup - [ ] CSV import/export
### v2.2 — Advanced Views ### v2.2 — Advanced Views
- [ ] Gantt view alternate layout - [ ] Gantt view alternate layout
- [ ] Kanban board (columns by status) - [ ] Kanban board (columns by status)
- [ ] Cross-project timeline view - [ ] Cross-project timeline view
- [ ] Workload heatmap showing deliverable density per day - [ ] Workload heatmap
- [ ] Archived projects with searchable history
### v3.0 — Intelligence Layer ### v3.0 — Intelligence Layer
- [ ] AI scheduling suggestions based on project cadence - [ ] AI scheduling suggestions
- [ ] Conflict detection — flag overloaded days - [ ] Conflict detection for overloaded days
- [ ] Natural language input ("Add final draft due next Friday to CODA") - [ ] Natural language deliverable input
--- ---