How to Manually Upgrade ChurchCRM

If the built-in upgrade isn't working for you, you can perform a manual upgrade by following these steps.

Prerequisites

• Access to your web server files (via FTP, SSH, or file manager)
• Access to your database (via phpMyAdmin, adminer, or command line)

---

Step 1: Download the Latest Release

Go to https://churchcrm.io/install.html and click the download button to get the latest .zip release package.

Step 2: Back Up Your Current Installation

This is critical — always back up before upgrading.

1. Back up your database:

   • Via phpMyAdmin: Select your ChurchCRM database → Export → Go
   • Via command line: mysqldump -u [username] -p [database_name] > churchcrm_backup.sql

2. Back up your configuration file:

   • Copy Include/Config.php to a safe location — this contains your database connection settings

3. Optionally back up the entire installation directory for a complete rollback option

Step 3: Extract and Upload the New Files

1. Unzip the downloaded release package
2. Upload/copy the extracted files over your existing ChurchCRM installation directory, replacing the old files
3. Make sure file permissions are correct — your web server user needs read (and in some cases write) access

Step 4: Restore Your Configuration

• Verify that your Include/Config.php file is still in place
• If it was overwritten during the file copy, restore it from your backup

Step 5: Run the Database Upgrade

1. Open your browser and navigate to your ChurchCRM URL
2. The system will automatically detect that a database upgrade is needed
3. You will be prompted to apply the upgrade — follow the on-screen instructions
4. Wait for the migration to complete

Step 6: Verify the Upgrade

1. Log in to ChurchCRM
2. Check the version number displayed at the bottom of the page to confirm you're on the latest version
3. Browse through your data (people, families, groups) to verify everything looks correct

---

Troubleshooting Tips

• White screen / 500 error after upgrade? Check your PHP error log and ensure your PHP version meets the minimum requirement (PHP 8.3+)
• Permission errors? Make sure your web server user (e.g., www-data) has write access to the ChurchCRM directory
• Stale UI after upgrade? Clear your browser cache (Ctrl+Shift+R / Cmd+Shift+R) to load the updated CSS/JS files
• Database upgrade not triggering? Try navigating directly to the setup page or check that your Include/Config.php database credentials are correct
• Need to rollback? Restore your database backup and original files from Step 2

---

If you run into any issues, feel free to ask here or open a new issue!