Church Cashbook Maintenance Manual

Checklist-driven procedure for safe planned maintenance, using the 503 maintenance page and maintenance.on toggle.

Planned maintenance procedure

Overview

Planned maintenance should be handled in a controlled way to protect financial data integrity and ensure a predictable return to service. Maintenance mode is enabled using a file-based toggle (maintenance.on) in the web root, which redirects all requests to the standalone 503.php page.

Pre-maintenance checklist

• ☐ Confirm scope of work (e.g. deployment, DB migration, server patching).
• ☐ Confirm expected duration and, if possible, an approximate return time.
• ☐ Confirm rollback plan exists (how to revert if something fails).
• ☐ Take a verified database backup.
• ☐ Take a codebase snapshot (or confirm the release tag/commit).
• ☐ Update /503.php operator settings (expected return time if known).

Enable maintenance mode

1. Create an empty file in the web root: maintenance.on.
2. Confirm any page now returns HTTP 503 (Service Unavailable).
3. Confirm the 503 page renders correctly and does not depend on the database.
4. Confirm the system is effectively read-only / unavailable to users during the maintenance window.

File and directory permissions (after install or upgrade)

After deploying new code (or changing the server configuration), ensure filesystem permissions are correct. This reduces the risk of accidental data exposure and prevents the web server from writing to application code.

Recommended permissions

• Code directories (app/modules/public assets): 0755
• Code files (php/js/css/html): 0644
• Sensitive files (config.php, .htaccess): 0600–0644 (prefer 0600 for config if possible)
• Runtime directories (logs/, logs/exports/, public/uploads/): 0755 or 0750 (must be writable if used)

Commands (run from project root)

# 1) Directories: read/execute for all, write for owner only
find . -type d -exec chmod 755 {} \;

# 2) Code files: readable by all, writable by owner
find . -type f -name "*.php"  -exec chmod 644 {} \;
find . -type f -name "*.js"   -exec chmod 644 {} \;
find . -type f -name "*.css"  -exec chmod 644 {} \;
find . -type f -name "*.html" -exec chmod 644 {} \;

# 3) Sensitive files (adjust paths if config is moved outside web root)
chmod 600 app/config.php 2>/dev/null || true
find . -name ".htaccess" -exec chmod 644 {} \;

# 4) Runtime directories (only if present / used)
chmod 755 logs 2>/dev/null || true
chmod 755 logs/exports 2>/dev/null || true
chmod 755 public/uploads 2>/dev/null || true

# 5) Quick safety check: list world-writable files/dirs (should return nothing)
find . -perm -002 -ls

After running these, re-check System information (Super Admin) to confirm there are no world-writable paths and that runtime folders required by the application are writable.

PHP error display (display_errors) — production safety check

Before returning the service to users, confirm that PHP errors are not displayed in the browser. This is often enabled in development environments (useful for debugging), but it should be disabled on a live system.

Required production settings

• display_errors = Off (users should not see raw PHP errors)
• log_errors = On (errors must be written to server logs)
• error_reporting = E_ALL (often shown as 32767)

How to check

1. Go to Admin → System information → Key PHP settings.
2. Confirm display_errors shows Off (recommended for production).
3. Confirm log_errors is enabled and note the error_log location if shown.

If correction is required

These settings are usually controlled by the server (php.ini, hosting control panel, or Apache/PHP configuration). After making changes, restart Apache/PHP if required, then re-check System information.

Final validation before returning to service

• ☐ display_errors is Off
• ☐ log_errors is On
• ☐ Custom 500.php page renders correctly (no raw PHP errors shown)

During maintenance

• ☐ Perform planned tasks.
• ☐ Monitor server and PHP error logs for unexpected issues.
• ☐ If schema changes are performed, validate database integrity and completion.
• ☐ Keep notes of any deviations from the plan and actions taken.

Post-maintenance checklist

1. Delete the maintenance.on file.
2. Confirm normal routing resumes (HTTP 200 on standard pages).
3. Confirm login works.
4. Confirm dashboard loads.
5. Perform a quick smoke test:
   • ☐ Add a test transaction (and void/remove if appropriate).
   • ☐ Run a standard report (e.g. Monthly Summary).
   • ☐ Check church selection and scope behaves correctly.
   • ☐ Check Gift Aid (if applicable to your environment).
6. Clear or reset /503.php operator text ($expectedResume, $extraNote) if you set it.
7. Record a maintenance summary (what changed, start/end times, any issues, and confirmation of success).

Maintenance record template

Date: ____________________________

Start time: _______________________    End time: _______________________

Reason: ______________________________________________________________

Changes applied: ______________________________________________________

Backup location: ______________________________________________________

Rollback required? ☐ Yes ☐ No

Issues encountered / actions:

______________________________________________________________

______________________________________________________________