waters-boards/README.md

Waters Boards

A self-hosted work-management app for the Waters Church team: boards, groups, items, statuses, people, dates, updates and automations. It covers the parts of monday.com the team uses and runs on the NAS beside the checklist app, so there's no monthly subscription.

It's one Node server (Express + SQLite) and a front end with no build step. It runs on desktop browsers and on phones, and a phone can install it to the home screen like an app.

---

What's in it

Workspaces & folders	Several workspaces, nested folders, favorites, a searchable sidebar. Drag boards into folders.
Boards	Colored, collapsible groups you can reorder. Items and subitems, drag-and-drop rows, multi-select bulk actions (duplicate, set status, move, archive, delete).
Column types	Status (custom labels and colors, with "done" labels), People, Date (optional time), Timeline, Text, Long text, Numbers (with unit), Dropdown, Tags, Checkbox, Rating, Link, Email, Phone, Files, Creation log, Last updated, Item ID. You can resize, reorder, rename, duplicate and change the type of any column. Group footers show summaries.
Views	Main table, Kanban (drag between lanes), Calendar (drag to reschedule; agenda list on phones), Timeline/Gantt (drag or resize bars), Chart (bar/pie plus KPIs), Files gallery.
Board tools	Search, person filter, advanced filters, sort, hide columns, CSV import and export (opens in Excel), duplicate or move boards, activity log.
Items	A side panel (full screen on phones) with Updates (@mentions, replies, likes, attachments, paste images), an Info tab with every column, Files, Activity history, subitems, move to another board.
Automations	"When status changes to X / a column changes / an item is created / a date arrives" → "move to group / notify / set status / assign / set date / clear / archive".
People	Google sign-in limited to company domains. The Inbox collects mentions, assignments, replies and automation alerts, and live presence shows who's online. My work lists everything assigned to you by due date. A Team directory and admin tools control roles and access.
Live	Changes appear on everyone's screen right away (server-sent events), with no refresh.
Migration	One-click import from monday.com through its API: workspaces, folders, boards, columns, groups, items, subitems, updates, replies and files.
Themes	Light, dark and night, or follow the system setting.
Safety	Nightly database snapshots (14 kept), files served only to signed-in users, deactivated people are signed out everywhere.

---

Run it locally

Needs Node 22.13+ (it uses Node's built-in SQLite, so there's nothing native to compile).

cd server
npm install
cp .env.example .env      # then set DEV_LOGIN=1 for passwordless local sign-in
npm run dev

Open http://localhost:3100. With DEV_LOGIN=1, "Developer sign-in" accepts any allowed-domain email. That button is disabled in production.

Data goes to server/data/ (boards.db, uploads/, backups/). The folder is gitignored.

---

Set up Google sign-in (once)

Google only allows sign-in from https addresses (or localhost), so the app needs a hostname behind the NAS reverse proxy, for example https://boards.watersmedia.org, set up the same way as check.watersmedia.org.

1. Go to https://console.cloud.google.com/ and sign in with the church Google Workspace admin account.
2. Create a project (e.g. "Waters Boards").
3. APIs & Services → OAuth consent screen: choose Internal, so only @waterschurch.org accounts can ever use it. Fill in the app name and support email, then save.
4. APIs & Services → Credentials → Create credentials → OAuth client ID
   • Application type: Web application
   • Authorized JavaScript origins: https://boards.watersmedia.org (and http://localhost:3100 for local testing)
   • No redirect URIs are needed.
5. Copy the Client ID (ends in .apps.googleusercontent.com) into GOOGLE_CLIENT_ID in .env.

The server checks every Google sign-in itself. It rejects any account outside ALLOWED_DOMAINS and any email Google hasn't verified.

Set ADMIN_PASSWORD in .env as a break-glass login for the ADMIN_EMAILS accounts, in case Google sign-in is ever misconfigured.

---

Deploy to the NAS

This follows the same pattern as the checklist app: Docker on the NAS, and Gitea Actions redeploys on every push to main that touches server/.

One-time setup on the NAS (10.1.1.5):

mkdir -p /volume2/docker/waters-boards
cp server/.env.example /volume2/docker/waters-boards/.env   # then fill it in

1. In the act_runner config.yaml on the NAS, add /volume2/docker/waters-boards to container.valid_volumes, then restart the runner. The runner refuses host mounts that aren't listed there.
2. Add a reverse-proxy rule: https://boards.watersmedia.org → http://localhost:3100. Allow WebSocket/streaming headers, because the live updates use a long-lived HTTP response.
3. In the Gitea repo, set Settings → Actions → Variables → DEPLOY_ENABLED = true. Until it's set, the deploy job is skipped, so pushes made before the NAS was ready don't show as failures.
4. Push to main, or run the workflow by hand from the Gitea Actions tab.

The workflow (.gitea/workflows/deploy.yml) never writes data/ or .env. It rebuilds the container in place without taking it down first, and fails loudly if .env is missing.

Manual deploy, without Gitea: copy server/ (minus data/, .env and node_modules/) to the NAS folder, then run docker compose up -d --build there.

---

Bring your monday.com data over

1. Sign in as an admin and open Admin → Import from monday.com.
2. In monday.com, click your avatar → Developers → My access tokens → copy.
3. Paste the token, click Load boards, pick boards (all are selected by default), then click Import.

People are matched by email. Anyone who isn't signed in yet gets a placeholder, and their assignments carry over when they first sign in with Google. You can re-run the import: boards that were already imported are skipped. The token is used only for that run and is never stored.

Subitems get their own columns in monday. Here, they show the parent board's columns, so subitem values land in the parent column with the same title. Any value without a matching column is kept as a note in the subitem's updates. Mirror, formula and connect-board columns come across as their text value.

---

Installing on phones

Open the site in Safari (iPhone) or Chrome (Android), then choose Share → Add to Home Screen or Install app. It opens full screen with a bottom tab bar (Home, My work, Boards, Inbox, Search). Pickers open as bottom sheets.

---

Backups

• Every night after 2am the app writes data/backups/boards-YYYY-MM-DD.db and keeps 14.
• For off-site copies, back up the whole data/ folder (database + uploads/) the same way the checklist data is backed up.
• To restore, stop the container, copy a snapshot over data/boards.db, and start it again.

---

Layout

server/
  server.js            Express app, admin import routes, nightly backup
  src/db.js            SQLite schema (node:sqlite) and helpers
  src/auth.js          Google ID-token sign-in, sessions, admin password, dev login
  src/api.js           REST API — boards, columns, groups, items, updates, files, views, automations, search
  src/model.js         Board loading, value formatting, activity log, notifications
  src/automations.js   Automation engine + daily date trigger
  src/realtime.js      Server-sent events
  src/importMonday.js  monday.com GraphQL importer
  src/templates.js     Board templates and default labels
  public/              Front end (Preact + htm, no build step)
    js/app.js          Shell, routing, sign-in
    js/board.js        Board header, views, toolbar, filters
    js/table.js        Main table (and the phone card list)
    js/cells.js        Column types: cells, pickers, summaries
    js/item.js         Item panel: updates, info, files, activity
    js/kanban.js · calendar.js · timeline.js · chart.js
    js/pages.js        Home, My work, Inbox, Search, Team, Admin