Performing Upgrades
This article will help you to upgrade your SocialEngine installation and troubleshoot some common problems associated with upgrades.
Backup your installation first
Before performing an upgrade, make a backup of your SocialEngine files and database. Most hosting providers include a backup utility with their control panel software. If you are not sure how to make a backup of your SocialEngine database and files, please contact your hosting provider and have them assist you with this. Alternately, refer to our Making and Restoring Backups article for assistance.
Video Tutorial
If upgrading from versions 4.0 up to 4.9.4p1, you will need to download this patch, unzip it and upload the file to your server, overwriting the folder on the server. This should be uploaded to the location on your server where SocialEngine is installed (in most cases, this is the public_html, httpdocs or other main folder). Be sure to do this step before following the next steps and after you have backed up your site files and database. This step will not be necessary when upgrading from 4.9.4p1 and up.
Instructions: Upgrading Your Installation
- After you have backed-up your data, login to the client area (http://www.socialengine.com/client) and download the version 4 upgrade package (which is listed as "SE4 Upgrade (4.x → 4.x.x)") along with the newest versions of any plugins. **This includes the Zend package upgrade. You don’t need to do that step separately from v4.9.1 and up.
- Login to your SocialEngine admin panel and go to the "Packages and Plugins" option under the "Manage" menu item. Click the "Install New Packages" link.
- Click "Install New Packages".
- Click on the Add Packages link and upload the files that you downloaded from the client area.
** NOTE: SocialEngine upload packages have a .tar extension. If you see a .zip file, you are not using the proper upgrade package and will need to download the correct file from the client area. See below for troubleshooting tips if the file won’t finish uploading. - Finally, follow the on screen instructions to upgrade your SocialEngine packages. Note that if you have made any changes to your SocialEngine files, the wizard will detect these changes and offer you the opportunity to overwrite or skip the modified files. Selecting the "overwrite" option will eliminate any changes you have made to those files. Selecting to "skip" the files will leave those files completely un-touched. Keep in mind that if you "skip" a file, any bug fixes that the upgrade would have provided will not be applied. If Upgrading and keeping customizations, make a list of all modified files and follow the steps below, or seek help from an Expert.
- Upgrade the SocialEngine core themes. This step is new from 4.9.0 and up. Navigate to Appearance > Theme Editor and click “Upgrade Theme (version)” for each one that has the button as shown.
- In the popup that opens, read the warning and note that this will overwrite the theme and remove any changes if you edited the core theme. We recommend making clones of the main themes and working on those so you don’t have any issues on upgrades. Click “Upgrade Theme” when you are ready to upgrade the theme.
- If upgrading from versions below 4.9.4p1, you’ll need to delete the folder temporary/packages-remove-(randomnumber)/core-base-4.9.4p1 from the server after upgrading. You can use FTP or your server’s file manager such as Cpanel, Plesk, etc.
- Clear cache after upgrading to ensure there are clean files being used for the site. This can avoid any odd issues from leftover files.
Common Issues
SocialEngine core upgrade file won’t upload
If you find that you can’t get the file to upload, it either keeps spinning or keeps saying you’ve not selected a file, you’ll want to have your host raise the PHP settings for upload_max_filesize and post_max_size as the upgrade file is large. Alternately, see the next step for where to FTP the upgrade .tar file in order to proceed with the upgrade.
Packages & Plugins has a white screen or error message
Mainly in Ubuntu servers, you may see a white screen or an error message about "cache_dir is not writable", set full permissions on temporary/cache.” This is resolved in the patch mentioned above. Please get the patch and upload it before trying to upgrade.
Server returned HTTP-Status #302
One way around this problem is to upload the file directly to SocialEngine using an FTP client. Log into your website over FTP and locate the "/temporary/package/archives/" directory in your SocialEngine path. Upload the tar file to this directory, and set the permissions of the file to 777. Then, proceed to the Manage > Packages & Plugins page. SocialEngine should be able to detect the file and extract its contents, allowing you to proceed with the rest of the installation.
Strange PHP errors after selecting more than 5 packages
Your server may not have sufficient memory allocated to PHP to upgrade all the packages selected. Try only checking 4 or 5 packages at a time until all packages have been upgraded.
Upgrading with Customizations
**Proceed with caution. You assume any and all risks and liability in customizing your SocialEngine files and in re-applying customizations. SocialEngine does not recommend altering the SocialEngine files. The following basic guide is provided as a general learning tool. SocialEngine assumes no liability for damages to your website as a result of following this guide.
This is a basic guide. It is recommended that those with advanced experience with the SocialEngine script continue with these steps. If you are a novice, or don’t know how to edit and/or compare files, you should seek Expert help for your upgrade.
Tools Needed
In addition to a copy of the SocialEngine files, we recommend that you have the following:
- SocialEngine Changelog open in a browser tab and/or a file compare program such as Beyond Compare.
- A list of files you’ve modified with modifications added(or copies of them saved on your computer) if you want to have edited files ready to load to your site after the upgrade. *Recommended as this saves time. If you don’t have a list of edited files, you can either wait to edit your files until you are in the Upgrade process where it will show you the modified files; or, you can use Beyond Compare and have it run a comparison of the SocialEngine files you downloaded and your SocialEngine backup files from your site.
- A good text editor such as NetBeans, Notepad++, Brackets.
Applying Customizations
Once you know which files need to be edited, follow the next steps.
- Apply your edits to the SocialEngine Upgrade files that you downloaded before. Make sure you save a copy of these so that you have it for the next time. It also helps in case you have issues on your site, you will know what to tell technicians if they ask.
- Perform the Upgrade steps above, skipping the modified files.
- Once the Upgrade is completed, upload the modified files you just made.
- Check the site. If you have errors, test by renaming one of your modified files on the server and loading the default SocialEngine file in its place. If the error goes away, you know it’s that modification. If it doesn’t go away, name the modified file back and try another until you find the culprit.
Note that your modifications may need to be updated. Be prepared to have to update your own code. Also note that deprecated functions, hooks, features may have been removed and your code might not work if it relies on those. You would need to either make new code or seek Expert help in cases like this.
Great work! Please feel free to contact us if you have any questions or need further tutorials. Visit our community to have more interactions with us and other clients or third party developers. We’d love to see you there!