visit.waterschurch.org/docs/DEPLOY-CPANEL.md

Deploying to cPanel (site administrator guide)

This guide assumes the standard cPanel layout /home/USER/. Replace USER with the account's username throughout. Nothing here changes DNS or publishes anything until step 8.

Current state (2026-09-22): visit.waterschurch.org already resolves to the same server as waterschurch.org (108.160.152.27) and currently 301-redirects to a Church Center form (waterschurch.churchcenter.com/people/forms/21186). That redirect lives either in the main site's .htaccess or in a cPanel Redirects entry and must be removed when this site goes live.

Fastest path: deploy/deploy.sh (SSH)

If you have SSH access (alias waterschurch in ~/.ssh/config), one command does steps 2, 5, 6 and 7 below:

deploy/deploy.sh --keep-redirect   # deploy, but keep visitors on the Church Center form (pre-launch)
deploy/deploy.sh                   # build, deploy and go live (removes the redirect)
deploy/deploy.sh --no-build        # re-upload the existing ./out

It preserves cPanel's own .htaccess blocks and .user.ini, never overwrites an existing ~/visit-private/.env, and prints the health check when done. The manual steps below describe what it does, for File Manager users or troubleshooting.

Status 2026-09-22 (evening): LIVE. Deployed with deploy/deploy.sh; the Church Center redirect is gone. INTEGRATION_MODE=live with Mailchimp (audience "Waters Church", datacenter us2) and Sinch (all five campus sub-accounts verified). The 12 merge fields exist in the audience. A real email-only test lead succeeded end to end; the SMS path is verified against Sinch auth but a live text has not yet been sent. Journey "New Visit" (id 5842) is still a draft and triggers only on Visit:Apollo Beach.

0. What you will need

• cPanel login for the waterschurch.org account
• The build package: run npm run build && npm run package → dist/visit-waterschurch-<version>-<date>.zip
• Filled-in .env values (Mailchimp key, Sinch key/secret, etc.) — see .env.example

1. Check the account's PHP

cPanel → Software → MultiPHP Manager (or Select PHP Version).

• Set the domain (once created) to PHP 8.1, 8.2 or 8.3.
• MultiPHP INI Editor / Select PHP Version → Extensions: ensure curl, pdo_sqlite, sqlite3, mbstring, json, openssl are enabled. (pdo_mysql only if you choose MySQL storage.)

Node.js is not required. If the account has "Setup Node.js App", ignore it.

2. Create the private configuration folder (outside the web root)

cPanel → Files → File Manager → navigate to /home/USER/ (the home directory, not public_html).

1. Create folder visit-private.
2. Inside it create folders data and logs.
3. Upload .env.example from the package (dist/env.example.txt), rename it to .env, and edit it in File Manager: fill in real values, set INTEGRATION_MODE=live only when ready to go live, and set a long random HASH_SALT.
4. Permissions (right-click → Change Permissions): folders 0750, the .env file 0640. PHP runs as your cPanel user under suPHP/LSAPI, so it can read and write these while the web server cannot serve them.

If your host runs PHP as a different user (rare), use 0755/0644 and rely on the folder being outside the document root.

3. Create the subdomain

cPanel → Domains → Domains (or Subdomains on older versions) → Create a New Domain:

• Domain: visit.waterschurch.org
• Untick "Share document root"; set Document Root to /home/USER/visit.waterschurch.org
• Submit. cPanel creates the folder and the DNS A record automatically because the zone is hosted here (ns1/ns2.waterschurch.org). The record already exists and points at this server, so nothing external changes.

Then remove the old redirect:

• cPanel → Domains → Redirects: delete any entry for visit.waterschurch.org, or
• File Manager → public_html/.htaccess: remove the RewriteCond %{HTTP_HOST} ^visit\. block that redirects to churchcenter.com.

Do this at the moment you are ready to launch (step 8); until then the redirect keeps working.

4. Enable SSL

cPanel → Security → SSL/TLS Status → tick visit.waterschurch.org → Run AutoSSL. Wait for the green padlock (usually under 5 minutes). If AutoSSL fails with a DCV error, make sure the document root exists and nothing blocks /.well-known/ (our .htaccess explicitly allows it).

Verify: https://visit.waterschurch.org/BUILD.txt shows the build id once files are uploaded (step 5). Force-HTTPS is handled by the site's own .htaccess; you do not need cPanel's "Force HTTPS Redirect" toggle, but enabling it is harmless.

5. Upload the build

1. File Manager → open /home/USER/visit.waterschurch.org/. Delete the placeholder cgi-bin folder if present.
2. Upload the zip from dist/, then right-click → Extract into this folder. Delete the zip.
3. Enable Settings → Show Hidden Files (dotfiles) and confirm .htaccess is present at the root and inside api/lib, api/cron, api/config.
4. Tell the API where the private folder is. Either:
   • leave the default (/home/USER/visit-private — the folder next to the document root), or
   • edit /home/USER/visit.waterschurch.org/.htaccess and uncomment SetEnv VISIT_PRIVATE_DIR /home/USER/visit-private with the real path.
5. Permissions: folders 0755, files 0644 (File Manager's defaults after extraction are fine).

The upload never requires editing generated files. To update the site later, rebuild locally and repeat steps 5.2–5.3 (or use File Manager → Upload with "Overwrite existing files"). An alternative for frequent updates is cPanel's Git Version Control pointed at a repo whose out/ is committed, or SFTP with rsync --delete out/ USER@host:visit.waterschurch.org/.

6. Verify the API

Open https://visit.waterschurch.org/api/health.php. You should see "ok": true and:

"private_dir_found": true, "env_file_found": true, "data_dir_writable": true,
"database": "ok (sqlite)", "campuses_loaded": 6, "https": true

integration_mode shows mock until you change it in .env. Fix anything false before continuing (most often: wrong VISIT_PRIVATE_DIR path or data folder not writable).

Confirm private paths are blocked (each must return 403):

• https://visit.waterschurch.org/api/lib/Config.php
• https://visit.waterschurch.org/api/config/campuses.json
• https://visit.waterschurch.org/api/cron/retry-integrations.php

7. Cron job for retries

cPanel → Advanced → Cron Jobs → add, every 5 minutes (*/5 * * * *):

VISIT_PRIVATE_DIR=/home/USER/visit-private /usr/local/bin/php /home/USER/visit.waterschurch.org/api/cron/retry-integrations.php >> /home/USER/visit-private/logs/cron.log 2>&1

Check the PHP binary path with MultiPHP Manager (often /usr/local/bin/php, /opt/cpanel/ea-php82/root/usr/bin/php, or /usr/local/bin/ea-php82). The job re-sends any Mailchimp/Sinch delivery that failed transiently (up to 5 attempts with backoff) and, if LEAD_RETENTION_DAYS is set, deletes fully-processed leads older than that.

Optional weekly export for staff (contains personal data — download and delete promptly):

VISIT_PRIVATE_DIR=/home/USER/visit-private /usr/local/bin/php /home/USER/visit.waterschurch.org/api/cron/export-leads.php --since=$(date -d '7 days ago' +%F) > /home/USER/visit-private/data/leads-week.csv

8. Go live

1. Set INTEGRATION_MODE=live in /home/USER/visit-private/.env.
2. Remove the Church Center redirect (step 3).
3. Submit one real test lead with your own email and mobile: confirm the Mailchimp contact + tags and the confirmation text arrive. Reply STOP to test opt-out routing, then re-subscribe.
4. Run through LAUNCH-CHECKLIST.md.

9. Updating content later

Change	Where	Then
Service times, address, phone, SMS number, campus status	config/campuses.json	npm run build → re-upload
Logo	assets/source/logos/ (same file names)	npm run build → re-upload
Photos	assets/source/photos/ (same file names)	npm run build → re-upload
FAQs, kids info, headlines, consent text	src/content/*.ts (bump consent.version if consent text changes)	npm run build → re-upload
Central contact number, privacy URL	.env (NEXT_PUBLIC_*)	npm run build → re-upload
API keys, mode, providers	/home/USER/visit-private/.env	takes effect immediately, no rebuild
SMS template	SINCH_CONFIRMATION_TEMPLATE in server .env	immediate

10. Files, permissions and logs

/home/USER/
├── visit.waterschurch.org/      document root (0755) — everything in out/
│   ├── .htaccess                HTTPS + canonical redirects, caching, security headers, 404
│   ├── index.html, 404.html, _next/, images/
│   └── api/                     PHP endpoints (public) + lib/ cron/ config/ (403)
└── visit-private/               NOT web accessible (0750)
    ├── .env                     secrets (0640)
    ├── data/leads.sqlite        lead store (created automatically)
    ├── data/retry.lock
    └── logs/app.log, cron.log   JSON lines; personal data and secrets are redacted

Rotate app.log occasionally (cPanel cron: find /home/USER/visit-private/logs -name '*.log' -size +20M -delete) or simply download and clear it.

11. Optional: MySQL instead of SQLite

cPanel → Databases → MySQL Database Wizard: create USER_visit + a user with ALL PRIVILEGES. In .env: DATABASE_DSN=mysql:host=localhost;dbname=USER_visit;charset=utf8mb4, DATABASE_USER, DATABASE_PASSWORD. Tables are created automatically on first request.

12. Content Security Policy

.htaccess ships a report-only CSP covering GTM, GA4, Meta, TikTok and Turnstile. After confirming the tags you actually use, change Content-Security-Policy-Report-Only to Content-Security-Policy and remove hosts you do not need.