# Church+ — Installation Guide (cPanel / shared or VPS hosting)

This guide walks through onboarding **one church** onto Church+. Repeat it for each new church. The control-plane (admin) database is set up once for the whole platform.

## Requirements

- PHP 8.1+ with PDO MySQL
- MySQL 5.7+ / MariaDB 10.4+
- A subdomain per church (e.g. `cornerstone.churchplus.app`) with HTTPS

---

## 0. One-time: set up the control plane

1. In cPanel, create a database `churchplus_admin` and a MySQL user with all privileges on it.
2. Import `sql/admin_schema.sql` via phpMyAdmin (or `mysql -u USER -p churchplus_admin < sql/admin_schema.sql`).
3. Every church you onboard gets a row in the `churches` table — that's your registry of who's on which plan, which database, and which subdomain.

## 1. Create the church's subdomain

In cPanel → Domains → Create a New Domain:
- Subdomain: `<slug>.churchplus.app`
- Document root: `~/churchplus/<slug>/public`

Enable AutoSSL for the subdomain.

## 2. Create the church's database

In cPanel → MySQL Databases:
- Database: `churchplus_<slug>`
- User: `churchplus_<slug>` with a strong generated password
- Grant the user ALL privileges on that database only

Import `sql/schema.sql` into the new database via phpMyAdmin.

## 3. Deploy the code

Upload the Church+ files so the structure looks like:

```
~/churchplus/<slug>/
├── config/
│   ├── config.example.php
│   └── config.php          ← you create this (step 4)
├── scripts/
│   └── seed_admin.php
├── sql/
├── src/
└── public/                  ← subdomain document root points here
    ├── assets/
    ├── includes/
    └── *.php
```

Only `public/` is web-accessible; config and source live above the web root.

## 4. Configure

```bash
cd ~/churchplus/<slug>
cp config/config.example.php config/config.php
php -r "echo bin2hex(random_bytes(32));"   # paste result into security.app_key
nano config/config.php                      # set db credentials and base_url
```

## 5. Create the first admin

```bash
php scripts/seed_admin.php "Pastor Jane Doe" jane@example.org "A-Strong-Password"
```

## 6. Register the church in the control plane

Insert a row into `churchplus_admin.churches` with the slug, subdomain, database name, plan, and contact info. (A platform admin UI for this is on the roadmap; until then, phpMyAdmin works.)

## 7. Hand it off

Send the church admin:
- Their login URL: `https://<slug>.churchplus.app`
- Their email and temporary password (have them change it at first sign-in via Staff Accounts → Reset password)
- A getting-started note: **Settings** (church name/address) → **People** → group into **Families** → adjust **Funds** → record first **Gifts** → take first **Attendance**.

---

## Operations

**Backups** — nightly, per church, kept separate:

```bash
mysqldump -u churchplus_<slug> -p churchplus_<slug> > /backups/<slug>-db-$(date +%F).sql
```

**Suspending a church** (non-payment / pause): swap `public/index.php` for a maintenance notice, or set `status = 'suspended'` in the control plane and add a status check to bootstrap. Data is untouched.

**Updates** — back up first, then replace `/src` and `/public/*.php` (leave `config/` alone), then apply any `sql/migrations/NNN.sql` files and verify login + dashboard.

**Removing a church** — final `mysqldump`, export confirmation to the church, then drop the database, MySQL user, and subdomain, and remove `~/churchplus/<slug>`.