ProDeck Adopter's Guide

01What you'd actually be adopting

Not a product. ProDeck is one church's custom tool: no vendor, no support contract, no license fee, and one maintainer (me), whose priority is my own Sunday. You'd be adopting a codebase — a well-documented one, but a codebase. The realistic ways to hold it:

• You have (or can borrow) a developer: fork the repo, and it's genuinely yours. The stack is mainstream — Rust + React in a Tauri desktop shell, plus two small Cloudflare Workers — and a competent full-stack dev is productive in it within a week.
• You don't: it still works — the core booth features run for years untouched (mine has no license checks and nothing that expires) — but bugs stay bugs and integrations drift as ProPresenter and Planning Center evolve. Go in with eyes open.

What it costs to run: a Mac in the booth, and if you want the phone/remote features, a Cloudflare account (free tier is enough) plus a domain (~$10/yr). That's the entire bill.

02Feature tour, with requirements

Every feature is independent — adopt the rows you want, ignore the rest. CORE needs only the booth Mac + ProPresenter + Planning Center. + X names the extra dependency.

Booth

Crew & cloud

Lobby & stream

03The stack it assumes

04What's specific to my church

The honest answer to "how personalized is this?" — in three tiers.

Tier 1 — just settings (change in the app, no code)

ProPresenter host, PCO credentials, all passwords and tokens, GA4 property/key, church coordinates, SPL calibration, MIDI ports and channels, Avantis host, audio channel routing, mic-position templates, checklists, call-time schedules, tap keyword→URL mappings, dashboard layouts. None of my values ship in the repo — a fresh install starts blank.

Tier 2 — your environment (nothing to edit in code)

Everything site-specific is either a Setting or a gitignored local file, so your fork never carries your values in source:

Tier 3 — shaped by my room (works for you, but review it)

• Console + key-send: the desk mirror speaks A&H (Avantis, dLive, SQ) and Behringer/Midas (X32, M32); the key-send exists because my FOH runs Waves LV1 with per-key scenes. A desk outside that list, or a different workflow → skip or rewrite those modules.
• Sunday shape: multi-service logic (auto-advance 8:00 → 9:30 → …), rehearsal-vs-service bucketing, and the readiness checklist reflect a multi-service Sunday with a volunteer crew. All configurable, but the shape is baked in.
• Legacy migration shims: two tiny startup routines migrate data from the app's earlier internal name — harmless on a fresh install, and documented in src-tauri/src/lib.rs and src/main.tsx.

05Limitations, stated plainly

• macOS only. The booth app is a Mac app. (Browsers/phones/kiosks connecting to it can be anything.)
• Single maintainer, no test suite. I fix what breaks on my Sundays. Your bugs are your fork's bugs unless we agree otherwise.
• Security model is passwords-over-HTTPS. Admin/member tiers, secrets never sent to browsers, admin actions gated server-side — sane, but it has never had a professional audit. If you expose it on your own domain, that's your risk to own.
• Self-signed, unnotarized app. macOS will warn on first launch; mic/screen permissions are pinned to the signing certificate you create (Part II covers this).
• Integrations track today's APIs — ProPresenter 7's network API, PCO API v2, GA4 Data API v1. Vendors move; someone has to move with them eventually.
• The viewer count is web-player-only. GA4 can't see Facebook/YouTube simulcast viewers, and the widget says so on its face.

06Fit checklist & effort estimate

You're a good fit if…

• ProPresenter 7 and Planning Center Services are already your Sunday backbone
• You can dedicate one always-on Mac to the booth
• Someone on or near your team can run terminal commands from a recipe (Part II is exactly that)
• You want the tap discs, crew phones, or unified dashboards badly enough to own a codebase

Think twice if…

• You need vendor support and SLAs — this has neither
• Your booth is Windows-only
• You mainly want the console features but run a desk outside the supported list

Realistic effort (for a comfortable tech volunteer)

07Phase 0 — try it on a spare Mac

Zero commitment: dev mode on any Mac (Intel or Apple Silicon) on your church network. No signing, no cloud, no install.

# prerequisites (one-time): Xcode command-line tools, Rust, Node 20+
xcode-select --install
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
brew install node   # or nodejs.org installer

# get the code (after I've added you to the repo)
git clone https://github.com/whiteoakmedia/prodeck.git
cd prodeck
bash scripts/setup.sh   # prereqs + config + dev mode, all guided

First run opens a setup wizard. Point it at ProPresenter (the ProPresenter machine's address (Find discovers it, or read the host and port from ProPresenter → Preferences → Network)) and press Connect for Planning Center, which signs you in on planningcenteronline.com itself — no password or token is typed into ProDeck. That's enough to evaluate everything tagged CORE in §2 — dashboards, show flow, slide grid, tracking, clear dock — plus SPL if you pick an audio input.

08Phase 1 — the booth install

Makes it permanent: a signed build that survives crashes and reboots unattended.

1 · Create your signing identity (once)

Keychain Access → Certificate Assistant → Create a Certificate: name it (e.g. YourChurch ProDeck), identity type Self-Signed Root, certificate type Code Signing. macOS pins microphone/screen permissions to this identity — keep using the same one forever, and never re-sign with hardened runtime (the install script refuses it for you).

2 · Create your updater keypair (once, optional)

npm run tauri signer generate -- -w ~/.prodeck/updater.key

Put the printed public key and your fork's release feed into the gitignored overlay src-tauri/tauri.local.conf.json (plugins.updater.pubkey / endpoints, plus bundle.createUpdaterArtifacts: true) — not into the committed tauri.conf.json. If you never publish updates, skip this step entirely. Guard the private key like a password: whoever holds it can ship code to your booth.

3 · Build, sign, install

TAURI_SIGNING_PRIVATE_KEY="$(cat ~/.prodeck/updater.key)" \
  npm run tauri -- build --bundles app --config src-tauri/tauri.local.conf.json
codesign --force --deep --sign "YourChurch ProDeck" \
  src-tauri/target/release/bundle/macos/ProDeck.app   # no hardened runtime
bash scripts/install-local.sh   # atomic swap into /Applications + watchdog handoff

Prefer a double-click installer? bash scripts/build-dmg.sh produces a drag-to-Applications ProDeck.dmg — hand it to anyone, no terminal needed to install (only to build). For an always-on booth, the script path below adds crash-relaunch and keep-alive that a plain drag-install does not.

scripts/install-local.sh refuses a bundle that isn't signed with your identity (or one signed with hardened runtime), and installs the watchdog LaunchAgent template from step 4 for you.

4 · The LaunchAgents

Ready-made templates live in deploy/launchagents/ — scripts/setup.sh --install installs and loads them for you. For reference:

Finish by enabling Browser Access in Settings (pick your admin + member passwords) and giving the booth Mac a DHCP reservation — do the ProPresenter Mac too, and skip the single most recurring failure I ever had.

09Phase 2 — your own cloud

Unlocks: crew phones anywhere, booth-off fallback, tap discs, kiosks beyond the LAN. Needs a Cloudflare account (free) and a domain on it.

1. Domain onto Cloudflare. Buy or transfer any domain; add it as a zone.
2. Point ProDeck at your domain — Settings → Browser Access → Public URL, and your zone's route in crew-edge/wrangler.local.jsonc (§4, Tier 2).
3. Deploy the two workers. In crew-edge/ and taplink-edge/: npx wrangler login then npx wrangler deploy. Set each worker's secrets with npx wrangler secret put <NAME> — the names are listed at the top of each worker's src/index.ts (admin token, PCO pair for the edge fallback, tap tokens).
4. Tunnel the booth. brew install cloudflared, then cloudflared tunnel login, cloudflared tunnel create booth, and a config at ~/.cloudflared/config.yml routing your hostname → http://localhost:8088. Add the DNS route (cloudflared tunnel route dns booth yourdomain.com) and wrap it in the com.prodeck.cloudflared LaunchAgent. Tunnel only the gateway port — never video.
5. Wire the booth to the edge: Settings → paste the edge admin token you chose in step 3. From then on install-local.sh keeps the edge's fallback copy in sync on every install.
6. Verify booth-off mode: quit ProDeck (watchdog off for a minute) and load your domain from a phone on cellular — you should get the read-only plan + chat. Restart, and it's live again.

10Phase 3 — the extras

11Ongoing care & staying current

• Fork, don't track. Fork the repo and make your Tier-2 edits on your fork. Pull from mine when something looks worth taking — my commits are messaged plainly. Nothing forces us to stay in sync.
• Back up two things off the booth Mac: the data folder ~/Library/Application Support/ProDeck/ (all settings, layouts, reports, crew accounts — settings.json inside it holds every secret) and your updater key. Your fork covers the code.
• Write your own succession page. I keep a companion "run and maintain this if I'm gone" handbook for my team; do the same on day one, while the setup is fresh. Ask me for my template.
• When something breaks Sunday morning: the app self-restarts on crash; ProPresenter reconnects are the most common fix; and if a feature that moves the desk (Automix, the speech mics, desk scenes) misbehaves, disarm it and mix by hand. Those never start on their own.