---
name: smallchurch-chms
description: >
  Installs, deploys, or sets up smallchurch CHMS for a house of worship or
  parachurch group on their own GitHub, Netlify, Supabase, and Resend
  accounts. Use when the user says install smallchurch CHMS, deploy the
  church membership app, set up the freeware CHMS, fork smallchurch-chms,
  bootstrap the first admin, import the people CSV, or walk the four free
  accounts. Do NOT use for the private FBC Wisner production app, for selling
  the software, or for hosting another church's data.
license: https://github.com/garrisondgriff/smallchurch-chms/blob/main/LICENSE
---

# smallchurch CHMS install

Church freeware. Houses of worship and parachurch groups only. Not OSI
open source. Read `LICENSE` in https://github.com/garrisondgriff/smallchurch-chms
before you copy files. Do not sell it. Do not rent it as a paid host. Do
not put member names in a public git file. Do not name this product
Planning Center.

Human training (large type, one account per page) lives at
https://smallchurch.work/chms/start. Follow that order. This skill does
the parts a pastor cannot click: database files, first admin, env vars.

If this file was pasted into chat, treat it as loaded. Ask the pastor for
the four account logins and the notebook keys before you change anything.

## Never

- Commit `.env`, `.env.local`, service_role keys, or Resend keys
- Clone the private FBC Wisner app
- Load CCLI lyrics or a real congregation's people into git
- Enable SMS sign-in
- Charge cards through this app
- Declare the install live until email sign-in works, a directory is
  visible, and a people CSV downloads. The church name must not be
  FBC Wisner.

## Order

1. GitHub copy
2. Netlify site from that copy
3. Supabase project
4. Resend API key
5. Database files (`supabase db push`)
6. One row in `public.churches`
7. Netlify env vars, then redeploy
8. First admin (`scripts/bootstrap-admin.mjs`)
9. Auth Site URL
10. Pastor signs in, sets church identity, imports people if they have a CSV

## 1. GitHub

Public source: `https://github.com/garrisondgriff/smallchurch-chms`

The pastor forks it into an account they control. Work in that fork. Do
not push secrets. Do not rewrite history on the public source repo.

## 2. Netlify

New site from the fork. Build settings come from `netlify.toml` in the
repo (`npm run build`, publish `.next.nosync`, Next.js runtime plugin).
The first deploy may fail until env vars exist. That is expected.

## 3. Supabase

New project. Region near the church. The pastor writes the database
password in a notebook.

After the project is ready, from a clone of their fork:

```
npx supabase login
npx supabase link --project-ref <PROJECT_REF>
npx supabase db push
```

`PROJECT_REF` is the subdomain in the Project URL
(`https://<PROJECT_REF>.supabase.co`). Use the database password when
asked. Do not dump production data into git.

Hosted projects do not run `supabase/seed.sql`. Do not load the Sampleton
fake congregation onto a real church's project.

## 4. One church row

`bootstrap-admin.mjs` fails if `public.churches` is empty. After push,
insert one row with the service role or SQL editor:

```
insert into public.churches (name) values ('THEIR CHURCH NAME');
```

One church per deployed copy. Do not insert a second tenant.

## 5. Resend

Create an API key named smallchurch. Store it as `RESEND_API_KEY`.
Built-in Supabase mail is fine while the pastor tests their own login.
Invite the whole list only after the church domain is verified in Resend.

## 6. Netlify environment variables

Set these, then trigger a new deploy:

- `NEXT_PUBLIC_SUPABASE_URL`
- `NEXT_PUBLIC_SUPABASE_PUBLISHABLE_KEY` (anon key)
- `SUPABASE_SERVICE_ROLE_KEY` (server only; never `NEXT_PUBLIC_`)
- `RESEND_API_KEY`

Optional later: `RESEND_WEBHOOK_SECRET`, `FIRST_ADMIN_EMAIL` (used only
when running the bootstrap script, not required at runtime).

## 7. First admin

From the fork, with env in the shell (not in a committed file):

```
FIRST_ADMIN_EMAIL=pastor@theirchurch.org \
NEXT_PUBLIC_SUPABASE_URL=https://<PROJECT_REF>.supabase.co \
SUPABASE_SERVICE_ROLE_KEY=... \
node scripts/bootstrap-admin.mjs
```

Safe to re-run. It never prints the service_role key. Sign-in is email
code only.

## 8. Auth Site URL

In the Supabase dashboard, Authentication, URL configuration:

- Site URL = the Netlify site URL (https)
- Add that URL to Redirect URLs

Without this, the sign-in code will not return to their site.

## 9. Church identity

After the pastor can sign in as admin, they open `/admin/church` and set
name, times, timezone, address, logo URL, and contact. Public pages read
those fields with no login.

## 10. People CSV

Template: `/admin/people/import` (columns `first_name,last_name,household,email,phone,status`).
Re-run skips the same email, or the same first name + last name +
household when email is blank. Status Member maps to voting_member.
Visitor maps to guest.

If they export from Planning Center People, map columns only. Planning
Center is the export they already have, not the product name.

Giving is a separate CSV under Admin, Giving. This app never charges a
card.

## Verify

The install is not done until all of these are true:

1. The Netlify URL loads.
2. The pastor receives an email code and signs in.
3. `/admin/church` shows their church name, not FBC Wisner and not Sampleton
   unless they are on a throwaway test.
4. People CSV export downloads.
5. No service_role value appears in browser developer tools.

If any check fails, stop. Fix that check. Do not tell them it is ready.