-
Notifications
You must be signed in to change notification settings - Fork 498
ChurchCRM Application Platform Prerequisites
This is the single source of truth for all ChurchCRM system requirements. All installation and deployment documentation should reference this page.
ChurchCRM has specific platform prerequisites, and a built-in mechanism to ensure that all prerequisites are met. If there are any unmet prerequisites, a message will be displayed during setup and a notification will be displayed during runtime.
Prerequisites are validated at every page load, so if the hosting environment is changed to an incomplete / unsupported model, a notification will appear.
Validation occurs in the getApplicationPrerequisites() function.
| Component | Requirement | Notes |
|---|---|---|
| PHP | 8.2 or higher | Required for all core functionality |
| Web Server | Apache 2.4+ with mod_rewrite | nginx may work but not officially supported |
| Database | MySQL 5.7+ or MariaDB 10.2+ | MariaDB 10.2+ or higher recommended |
| Memory | 256MB+ PHP memory limit | 512MB+ recommended for larger congregations |
| Storage | 500MB+ available space | Depends on attachments and data size |
Status: REQUIRED
ChurchCRM requires PHP 8.2 or higher as the absolute minimum. This requirement is enforced in the application and verified at every page load.
Installation:
- Shared Hosting (cPanel): Select PHP 8.2 or higher from your hosting control panel
- Self-Hosted Linux: Follow the steps at Install Self Hosted Linux or Self-Hosted on RockyLinux
- Local Development: Use Docker Development Environment or GitHub Codespaces
Tested Versions: The application is tested and verified to work with the following PHP versions:
- PHP 8.2 (minimum supported)
- PHP 8.3
- PHP 8.4 (latest)
For a complete list of tested versions and configurations, see the GitHub Actions CI workflow.
The following PHP extensions must be installed and enabled. These are validated during setup and at every page load via the getApplicationPrerequisites() function.
Core Database & String Handling:
Purpose: Arbitrary precision arithmetic
Installation: php-bcmath package
Purpose: HTTP requests and external API communication
Installation: php-curl package
Purpose: JSON encoding/decoding (API responses)
Installation: Usually bundled with PHP
Purpose: Multibyte string handling (UTF-8 support)
Installation: php-mbstring package
Purpose: MySQL/MariaDB database access
Installation: php-mysql or php-mysqli package
Purpose: XML parsing and processing
Installation: php-xml package
Image & Content Processing:
Purpose: Image manipulation (profile pictures, charts)
Installation: php-gd package
Additional Requirements: Requires FreeType library for text rendering
Purpose: Read EXIF data from uploaded images
Installation: php-exif or usually included with php-gd
Purpose: Detect file types and MIME types
Installation: Usually bundled with PHP
Internationalization & Localization:
Purpose: Localization and translation support
Installation: php-gettext package
Purpose: Internationalization and Unicode support
Installation: php-intl package
Archive & Data Handling:
Purpose: PHP Archive support (installation/updates)
Installation: Usually bundled with PHP
Purpose: SOAP web services support
Installation: php-soap package
Purpose: ZIP file handling (imports/exports, backups)
Installation: php-zip package
Character Encoding & Cryptography:
Purpose: Character set conversion for text handling
Installation: Usually bundled with PHP
Purpose: PHP session support
Installation: Usually bundled with PHP
Purpose: Modern cryptography (password hashing, encryption)
Installation: php-sodium package
Regular Expression Support:
Purpose: Regular expression support with Unicode (UTF-8)
Installation: Usually bundled with PHP
Requirement: Must support UTF-8 character matching (preg_match with /u flag)
Apache 2.4+ with mod_rewrite
ChurchCRM currently requires Apache's mod_rewrite module for URL routing. While we'd like to deprecate this requirement, it still exists. If you know mod_rewrite is loaded and working on your Apache setup, it is SAFE to ignore this prerequisite during setup.
nginx compatibility: nginx may work but is not officially supported or tested.
MySQL 5.7+ or MariaDB 10.2+
- MariaDB 10.2 or higher is recommended for better performance
- Database must support:
- UTF-8 character set
- InnoDB storage engine
- Foreign key constraints
These write permissions are validated during setup and at every page load via the getFilesystemPrerequisites() function.
Path: Include/ directory (contains Config.php)
Permission Required: Writable
Purpose: Store application configuration during setup
Typical Permission: 755 or 775
User: Must be writable by PHP process owner (www-data, apache, or similar)
Path: Images/ directory
Permission Required: Writable (recursively)
Purpose: Store user uploads and generated images
Typical Permission: 755 or 775
User: Must be writable by PHP process owner
Subdirectories That Must Be Writable:
-
Images/Family/- Family profile pictures and documents -
Images/Person/- Person profile pictures and photos
Path: System temporary directory (usually /tmp on Linux)
Permission Required: Writable
Purpose: PHP session storage, file uploads, temporary operations
Configuration: Controlled by php.ini session settings
Note: Ensure PHP's temporary directory is not mounted as noexec
Regular expression support with Unicode handling (usually built-in to modern PHP)
System should support UTF-8 locales for proper text handling
- Minimum: 256MB
- Recommended: 512MB or higher
- Larger congregations may need 1GB+
Configuration: memory_limit in php.ini
- Minimum: 30 seconds
- Recommended: 60+ seconds for data imports
- Large reports may need higher values
Configuration: max_execution_time in php.ini
See PHP Max Execution Time for detailed tuning guidance.
Must be turned OFF (deprecated PHP feature)
Must be enabled and configured:
file_uploads = On-
upload_max_filesize- recommend 10MB+ -
post_max_size- should match or exceed upload_max_filesize
- Installation Guide ← Start here!
- First Run Setup
- Features Overview
- Upgrade Guide
- Backup & Restore
- Rollback Procedures
- File Permissions
- Troubleshooting
- Logging & Diagnostics
- SSL/HTTPS Security
- Localization