CivicPlexus Self-Hosting & Deployment Guide

A non-developer can follow this guide end-to-end and stand up a secure, production-ready CivicPlexus deployment — with or without Lovable — in roughly two hours. Each section ends with a Did it work? check.

CivicPlexus is a full local-government HRIS + talent suite (recruiting, onboarding, core HR, payroll, benefits, performance, compliance), not just an onboarding tool. Plan capacity accordingly.

1. What you'll end up with

                 ┌──────────────────┐
   Users  ─────► │  Cloudflare CDN  │ ──► HTTPS, WAF, rate limiting
                 └────────┬─────────┘
                          ▼
                 ┌──────────────────┐
                 │  SSR runtime     │ ──► TanStack Start app (SSR + API)
                 │  (Workers / Node)│
                 └────────┬─────────┘
                          ▼
                 ┌──────────────────┐
                 │ Supabase Project │ ──► Postgres + Auth + Storage + pg_cron
                 └────────┬─────────┘
                          ▼
                 ┌──────────────────┐
                 │   Email Provider │ ──► Resend / SES / SendGrid
                 └──────────────────┘

Cost estimate (small municipality, < 500 employees):

• Supabase Pro: ~$25/mo
• Cloudflare Workers Paid or Render/Fly Starter: ~$5–$20/mo
• Resend or SES: ~$0–$20/mo
• Domain: ~$15/yr
• Total: ~$35–$70/month

Time required: ~2 hours (plus DNS propagation, up to 24 hours).

2. Decisions before you start

This guide covers every deployment target in §8.

3. Accounts to create

Sign up for all of these now and turn on two-factor authentication for each:

1. GitHub — https://github.com (free)
2. Supabase — https://supabase.com (free tier OK to start; upgrade to Pro before go-live)
3. Your deployment host — Cloudflare, Render, Fly.io, Railway, or your VM provider
4. Domain registrar — whoever sold you the domain
5. Resend — https://resend.com (free tier OK to start)

Did it work? ✅ You can log into all five with MFA enabled.

4. Get the code

Install prerequisites

• macOS: brew install git node bun
• Windows: install Git for Windows, Node LTS, then in PowerShell: irm bun.sh/install.ps1 | iex
• Linux: sudo apt install git nodejs && curl -fsSL https://bun.sh/install | bash

Clone and install

git clone https://github.com/<your-org>/civicplexus.git
cd civicplexus
bun install

Did it work? ✅ bun install completes without errors.

5. Provision the database (Supabase Cloud — recommended)

1. https://supabase.com → New project. Pick a strong DB password and save it in a password manager. Region: closest to your users.
2. Once provisioned, go to Settings → API and copy these into your password manager:
   • Project URL (e.g. https://abcd.supabase.co)
   • anon (publishable) key
   • service_role key (treat like a root password — never paste into client code)
3. Install the Supabase CLI: bun add -g supabase
4. Link and push migrations:

   supabase login
   supabase link --project-ref <your-project-ref>
   supabase db push
   

5. Auth → Providers: enable Email and Google. For Google, follow the in-product wizard to register OAuth credentials.
6. Auth → Email: enable Have I Been Pwned password check. Disable Confirm email only if you have a closed user base.
7. Auth → URL Configuration: set Site URL to your final domain (e.g. https://hr.cityofx.gov). Add the same to Redirect URLs.
8. Storage: create these private buckets (leave "Public" off on all of them):
   • onboarding-documents
   • job-applications
   • training-evidence
   • offer-letters
   • payroll-exports
   • compliance-exports
   • official-photos
   • official-documents

Did it work? ✅ supabase db push reports "Finished". The Tables UI shows employees, job_requisitions, payroll_runs, performance_reviews, etc.

6. Alternative: self-hosted Supabase on a single VM

Skip if you used §5.

1. Provision a VM (Hetzner CCX23, DigitalOcean 4 vCPU/8 GB, or AWS Lightsail $40 plan).
2. Install Docker + Docker Compose.
3. git clone https://github.com/supabase/supabase && cd supabase/docker
4. Copy .env.example to .env, generate strong values for POSTGRES_PASSWORD, JWT_SECRET, ANON_KEY, SERVICE_ROLE_KEY (use https://supabase.com/docs/guides/self-hosting/docker#generate-api-keys).
5. docker compose up -d
6. Install Caddy as a reverse proxy with automatic Let's Encrypt:

   hr.cityofx.gov {
     reverse_proxy localhost:3000
   }
   

7. Schedule nightly pg_dump to S3/B2:

   0 2 * * * docker exec supabase-db pg_dumpall -U postgres | gzip | aws s3 cp - s3://your-backups/$(date +\%F).sql.gz
   

8. Test the restore before you go live.

Did it work? ✅ https://hr.cityofx.gov returns the Supabase Studio login.

7. Configure secrets

Create .env.local in the project root (never commit this file):

# Client-visible (safe to bundle)
VITE_SUPABASE_URL=https://abcd.supabase.co
VITE_SUPABASE_PUBLISHABLE_KEY=eyJhbGci...
VITE_SUPABASE_PROJECT_ID=abcd

# Server-only (host secrets, never bundle)
SUPABASE_URL=https://abcd.supabase.co
SUPABASE_PUBLISHABLE_KEY=eyJhbGci...
SUPABASE_SERVICE_ROLE_KEY=eyJhbGci...          # service role — keep secret
LOVABLE_API_KEY=lv_xxx                          # optional — only if AI features are used
BENEFITS_WEBHOOK_SECRET=<32-byte hex>          # openssl rand -hex 32
REMINDERS_CRON_SECRET=<32-byte hex>            # openssl rand -hex 32
EMAIL_FROM=hr@cityofx.gov
RESEND_API_KEY=re_xxx

Generate strong secrets with openssl rand -hex 32. Store all values in your password manager.

Did it work? ✅ bun run dev boots and you can sign up locally.

8. Deploy the app (pick one)

CivicPlexus is built on TanStack Start v1 with the Vite plugin. The build emits both a static client bundle and a server bundle — you always need an SSR runtime. Pure static hosts (plain S3, Netlify static, GitHub Pages) will not work; see §8.D.

8.A Cloudflare Workers (recommended, no Lovable)

Fastest, cheapest, globally distributed. Use the nodejs_compat flag so server functions can use fs, crypto, Buffer, stream, etc. Avoid Node-only npm packages here (sharp, puppeteer, child_process); use Worker-compatible equivalents.

1. bun add -g wrangler && wrangler login
2. Build: bun run build
3. Set secrets in Cloudflare (run each line):

   for v in VITE_SUPABASE_URL VITE_SUPABASE_PUBLISHABLE_KEY VITE_SUPABASE_PROJECT_ID \
            SUPABASE_URL SUPABASE_PUBLISHABLE_KEY SUPABASE_SERVICE_ROLE_KEY \
            LOVABLE_API_KEY BENEFITS_WEBHOOK_SECRET REMINDERS_CRON_SECRET \
            EMAIL_FROM RESEND_API_KEY; do wrangler secret put "$v"; done
   

4. Deploy: wrangler deploy
5. In Cloudflare DNS, add a CNAME hr → <your-worker>.workers.dev, then attach a Custom Domain in the Workers UI for automatic TLS.

Did it work? ✅ https://hr.cityofx.gov returns the sign-in page; wrangler tail shows healthy SSR logs.

8.B Generic Node host (Render / Fly.io / Railway)

Use this if you prefer a familiar PaaS or need Node-only npm packages.

1. Build locally to confirm: bun run build. Output lands in .output/server/index.mjs.

2. Add a start script to package.json (one-time): "start": "node .output/server/index.mjs".

3. Choose your host:

   Render — add a render.yaml at the repo root:

   services:
     - type: web
       name: civicplexus
       runtime: node
       buildCommand: bun install && bun run build
       startCommand: node .output/server/index.mjs
       envVars:
         - key: NODE_VERSION
           value: "20"
   

   Fly.io — fly launch --no-deploy, then in fly.toml:

   [build]
     builder = "paketobuildpacks/builder:base"
   [processes]
     app = "node .output/server/index.mjs"
   [[services]]
     internal_port = 3000
     protocol = "tcp"
     [[services.ports]]
       port = 443
       handlers = ["tls", "http"]
   

   Railway — connect the repo; Railway auto-detects Bun. Set the start command to node .output/server/index.mjs. Add a custom domain in the Settings tab.

4. In the host's dashboard, paste every variable from §7 as an environment variable.

5. Deploy. Logs live in the host's UI.

Did it work? ✅ The host's domain returns the sign-in page; deploy logs show no missing env vars.

8.C Docker on a VM

Use this for full control or air-gapped environments.

Dockerfile:

FROM oven/bun:1 AS build
WORKDIR /app
COPY . .
RUN bun install --frozen-lockfile && bun run build

FROM node:20-alpine AS run
WORKDIR /app
COPY --from=build /app/.output ./.output
COPY --from=build /app/package.json ./
ENV NODE_ENV=production
EXPOSE 3000
CMD ["node", ".output/server/index.mjs"]

docker-compose.yml (with Caddy for TLS):

services:
  app:
    build: .
    env_file: .env.local
    restart: unless-stopped
  caddy:
    image: caddy:2
    ports: ["80:80", "443:443"]
    volumes:
      - ./Caddyfile:/etc/caddy/Caddyfile
      - caddy_data:/data
    restart: unless-stopped
volumes:
  caddy_data:

Caddyfile:

hr.cityofx.gov {
  reverse_proxy app:3000
}

Bring it up: docker compose up -d --build.

Did it work? ✅ curl -I https://hr.cityofx.gov returns 200; docker compose logs app is clean.

8.D Why static hosting will NOT work

CivicPlexus needs an SSR runtime for loaders, server functions, and /api/* routes. Do not try to deploy to plain S3, Netlify static, Cloudflare Pages without Functions, or GitHub Pages — every authenticated page will fail to render and every API call will 404. If you want a managed static-style experience, use Cloudflare Pages with Functions (same Worker runtime as 8.A) or Netlify/Vercel with their SSR adapters.

9. Email

1. In Resend (or your provider), add your sending domain and add the SPF / DKIM / DMARC DNS records they show you.
2. Verify the domain.
3. Set EMAIL_FROM to hr@yourdomain.gov and RESEND_API_KEY to the API key.

Did it work? ✅ Trigger any notification (e.g., create a hire request) — the email lands in your inbox within a minute.

10. Schedule recurring jobs

CivicPlexus exposes signed cron endpoints under /api/public/hooks/. The shared REMINDERS_CRON_SECRET from §7 must be sent as a bearer token.

Option A — pg_cron (Supabase Cloud):

select cron.schedule(
  'civicplexus-reminders', '0 * * * *',
  $$ select net.http_post(
       url := 'https://hr.cityofx.gov/api/public/hooks/reminders',
       headers := jsonb_build_object('Authorization', 'Bearer ' || current_setting('app.cron_secret'))
     ) $$
);

Then ALTER DATABASE postgres SET app.cron_secret = '<REMINDERS_CRON_SECRET>';.

Option B — generic crontab (any Linux host):

0 * * * *  curl -fsS -H "Authorization: Bearer $REMINDERS_CRON_SECRET" https://hr.cityofx.gov/api/public/hooks/reminders
0 7 * * *  curl -fsS -H "Authorization: Bearer $REMINDERS_CRON_SECRET" 'https://hr.cityofx.gov/api/public/hooks/reminders?job=cert-expiry'
0 2 * * *  curl -fsS -H "Authorization: Bearer $REMINDERS_CRON_SECRET" 'https://hr.cityofx.gov/api/public/hooks/reminders?job=retention-sweep'

/api/public/hooks/benefits-callback is a webhook, not cron — the carrier calls it, signed with BENEFITS_WEBHOOK_SECRET.

Did it work? ✅ After one hour, the audit log shows cron_run events.

11. Create the first admin

1. Sign up at https://hr.cityofx.gov with your work email.
2. In Supabase SQL editor:

   INSERT INTO public.user_roles (user_id, role)
   SELECT id, 'hr_admin' FROM auth.users WHERE email = 'you@city.gov';
   

3. Sign out and back in.

Did it work? ✅ Sidebar shows People, Recruiting, Pay, Performance, Compliance, Admin groups.

12. Security hardening checklist

Tick every item before you let real employees in:

• HTTPS forced + HSTS ≥ 6 months on Cloudflare / your CDN.
• CSP header set in src/routes/__root.tsx head() (default-src 'self'; img-src 'self' data: https:; etc.).
• MFA on every account (Supabase, host, registrar, email, GitHub).
• Supabase service-role key rotated after initial setup; only in your password manager and host secrets.
• Supabase Auth redirect URLs limited to your domain (no localhost, no wildcards).
• HIBP password check enabled.
• Cloudflare WAF managed ruleset ON (or equivalent on your host).
• Rate limiting on /api/public/* (60 req/min/IP).
• attachSupabaseAuth is the only auth middleware in src/start.ts (no duplicates, no replacements).
• Every /api/public/* route validates a signature or shared secret before doing work.
• user_roles is read only via private.has_role(...) in policies — never selected directly from client code.
• Backups: Supabase Pro daily backups, 30-day retention. Test restore quarterly.
• Audit log reviewed weekly for first month, monthly thereafter.
• Access review every 90 days — remove stale admin accounts.
• Document retention cron active (daily sweep based on org_settings.retention_policy).
• Supabase linter clean: run supabase db lint after every migration.
• Dependency scan monthly: bun audit.
• .env.local in .gitignore (it already is — verify).

13. Compliance notes

14. Updating the app

git pull
bun install
supabase db push     # if there are new migrations
bun run build
# then re-deploy via your chosen path in §8

Rollback: wrangler rollback (Workers), redeploy a previous image (Docker), or git checkout <prev-tag> then redeploy. For DB, restore the pre-update backup.

15. Monitoring & alerts

• Cloudflare Workers users: Cloudflare Analytics (requests, errors, WAF hits) + wrangler tail for live logs.
• Node host users: the host's built-in log viewer (Render Logs, Fly fly logs, Railway Logs).
• Docker users: docker compose logs -f app; ship logs to Loki/Datadog if you have one.
• Supabase Logs: SQL errors, Auth errors, edge runtime — same across every deploy path.
• Sentry (free tier): add @sentry/react and your runtime's adapter with your DSN.
• /healthz endpoint: configure Better Uptime or UptimeRobot to ping every 5 min and SMS on failure.

16. Disaster recovery

Restore drill (run quarterly):

1. Spin up a fresh Supabase project.
2. Download the latest backup from Supabase → Database → Backups.
3. Restore via psql < backup.sql.
4. Point a staging deployment at the restored DB. Sign in. Verify counts: select count(*) from employees; matches production.
5. Document time-to-restore.

Secret rotation runbook:

1. Generate a new value (openssl rand -hex 32).
2. Set it on your host (wrangler secret put, Render dashboard, fly secrets set, etc.).
3. Redeploy.
4. If rotating SUPABASE_SERVICE_ROLE_KEY: Supabase → Settings → API → Reset service_role. Update host secret. Redeploy.

17. Troubleshooting

18. Appendix

Full env var reference

DNS records (example)

Storage bucket policies

All six buckets in §5.8 are private. RLS lets a user read/write only their own folder (auth.uid()::text = (storage.foldername(name))[1]) except payroll-exports and compliance-exports, which are HR-only.

Cron jobs (default)

• civicplexus-reminders — hourly
• civicplexus-cert-expiry — daily 07:00 local
• civicplexus-retention-sweep — daily 02:00 local
• civicplexus-demo-reset — hourly (rolls back demo-user changes older than 24 hours)

Modules added since 1.0

These ship enabled by default and can be toggled per tenant from /admin-modules:

• Timekeeping — clock-in/out, OT, comp-time, exempt schedules
• Public Safety Shifts — 207(k) work periods, Kelly/Pitman/24-48 rotations
• HR + Finance — department FTE budgets and requisition headroom checks
• Payroll Profiles — Tyler Munis, BS&A, ADP, Paycom export templates
• Identity / SCIM — Entra/Okta SAML + SCIM v2 (/api/public/scim.v2.Users)
• CBA — union contract registry
• OSHA — 300/300A incident log and summary
• LMS Imports — external training ingest → TCOLE mapping. Manual CSV upload plus native connectors for Chamilo (REST v2), Moodle (Web Services REST), and Forma LMS (JSON API). Connections are stored in lms_connections, runs in lms_sync_runs, both HR-admin RLS. Auto-sync is driven by pg_cron job lms-auto-sync-hourly hitting /api/public/hooks/lms-sync. Per-connection API tokens live as project secrets named LMS_<connection_id>_TOKEN.
• Cascades — org-wide directives with AI rollup
• 1-on-1 Templates — HR-managed question sets
• ID Badges + QR Verify — CR80 PDFs, public /api/public/badge/{serial}
• Offline PWA — service worker (/sw.js) with Background Sync against /api/public/hooks/offline-replay

LiveKit (live interview rooms) {#livekit-live-interview-rooms}

Live multi-party interview rooms are powered by LiveKit. The rest of the Interviews module — scheduling, scorecards, candidate two-take async video responses — works without it. Enabling LiveKit only lights up the Join room action on each scheduled interview.

Steps:

1. Create a project at cloud.livekit.io (free tier is sufficient for evaluation) or self-host LiveKit Server.
2. From the project page, copy the WebSocket URL (wss://your-project.livekit.cloud), the API Key, and the API Secret.
3. Save them as three backend secrets — names must match exactly:
   • LIVEKIT_URL
   • LIVEKIT_API_KEY
   • LIVEKIT_API_SECRET
4. Reload an interview detail page. HR admins will no longer see the Enable live interview rooms banner, and panelists can click Join room.
5. (Optional) To enable composite recordings, configure S3-compatible egress on the LiveKit project. Rooms function without egress; only the recording side is skipped, while the consent log and scorecards remain in place.

Did it work? ✅ On /interviews/<id>/room, the setup banner is gone and clicking Join interview opens the LiveKit room without an error toast.

Common failures:

• Live interviews are not configured… toast → one of the three secrets is missing or misnamed.
• Token mints but the room never connects → LIVEKIT_URL is https://… instead of wss://…, or the project region is unreachable from the SSR runtime.
• invalid api key from LiveKit → secret was rotated in the LiveKit dashboard; update LIVEKIT_API_SECRET to match.

PWA / Background Sync deployment notes

• The build emits /sw.js via vite-plugin-pwa in injectManifest mode (source: src/sw.ts).
• /api/public/hooks/offline-replay verifies the user's Supabase bearer token before executing queued RPCs — do not place it behind additional auth middleware.
• iOS Safari does not implement Background Sync; the worker falls back to a drain-queue postMessage while at least one tab is open. Plan field training accordingly.
• vite.config.ts denylists /~oauth, /api/, and /auth from the service worker navigation handler. Add any additional auth callback paths to the denylist if you extend the auth flow.

Cost worksheet

You're done. Welcome new hires — and run payroll — with confidence.

Appendix — Installer, Health, Backup, Restore (v1.1)

CivicPlexus ships first-class shell scripts so a non-developer can install, back up, and restore without writing SQL or Bash.

One-command install

cp .env.example .env        # fill in SUPABASE_* and AI_PROVIDER
./scripts/install.sh        # verifies prereqs, applies migrations, builds

install.sh requires bun, psql, and the Supabase CLI (npm i -g supabase). Re-running it is safe — migrations are idempotent.

First HR admin

psql "$SUPABASE_DB_URL" -f scripts/seed-first-admin.sql -v email=you@city.gov

The target user must have already signed up once (so an auth.users row exists).

Health probe

GET /api/public/health returns JSON with database + AI status; 200 when healthy, 503 when degraded. Point your uptime monitor at it.

curl https://hr.yourcity.gov/api/public/health

Nightly backup

BACKUP_DIR=/var/backups/civicplexus ./scripts/backup.sh

Produces db.sql.gz, schema.sql, storage bucket copies, and SHA256SUMS. Retains the last 30 nightly runs. Schedule via cron:

15 2 * * *  cd /opt/civicplexus && BACKUP_DIR=/var/backups/civicplexus ./scripts/backup.sh >> /var/log/civicplexus-backup.log 2>&1

Restore

./scripts/restore.sh /var/backups/civicplexus/20260101T021500Z

Verifies SHA-256 checksums, asks for explicit confirmation, then restores. Run a smoke test (/api/public/health + sign-in) before reopening to users.

RLS guardrail (CI)

psql "$SUPABASE_DB_URL" -v ON_ERROR_STOP=1 -f scripts/check-rls.sql

Fails if any public.* table lacks RLS or has zero policies — wire it into your CI pipeline so a future migration cannot ship a table without policies.

AI provider pluggability

Set AI_PROVIDER in .env:

The health endpoint reports ai_not_configured when the chosen provider is missing credentials, so misconfiguration surfaces immediately.

15. Governance (Elected Officials & Boards)

Municipal governance data lives alongside HR but has its own tables, buckets, roles, and cron jobs.

15.1 Tables

official_bodies, official_seats, officials, official_terms, official_meetings, official_attendance, official_disclosures, officials_reimbursements. All are RLS-enabled.

15.2 Storage buckets

Both private:

• official-photos — headshots for the public roster (served via signed URLs).
• official-documents — oaths, disclosures, appointment letters (clerk/HR only).

15.3 Roles

Add to your app_role enum if not present:

• city_clerk — full CRUD on governance tables and roster exports.
• elected_official — read-only on own record and term; may submit own disclosures.

HR admins retain full override via hr_admin.

15.4 Public roster privacy flags

Per-record flags on officials:

• public_visible (bool, default false) — required for the record to appear on /officials and in the public CSV/PDF exports.
• public_show_contact (bool, default false) — email/phone shown publicly only when true.

The officials_public_read policy and exportPublicRosterCsv server function both enforce these flags. Set defaults per body when onboarding a new commission.

15.5 Scheduled jobs

Register in pg_cron (or the equivalent scheduler):

Term status changes to resigned or removed fire an immediate notification via officials_notify_targets() — no cron needed.

15.6 Health check

Governance is reported under modules.governance in the health probe. If storage buckets are missing, the probe returns governance_storage_missing.