Installation and Upgrading 08 August 2008 / Updated: 03 December 2022
NOTE: There are a number of 3rd party install scripts available for Zenphoto (and other CMS). These scripts are often used by webhosts to provide "one-click-installs". Scripts such as SimpleScripts version 3 seem to execute each of the necessary Zenphoto setup steps and should produce identical results as following the installation steps below.
Others try to reproduce the end result of an installation. These latter may not reliably accomplish their goal and leave a flawed installation. Also please note that some hosts seem to provide outdated versions for unknown reasons.
We do not test these scripts and cannot provide support if their use causes Zenphoto problems.
- Download the latest version of Zenphoto.
- Extract the files to your computer then upload all files and folders as listed below to your web directory via FTP. You can upload them either in the root of your webspace or within a subfolder.
- Create a MySQL database.
- If you install on local server please also read Using Zenphoto on local servers.
- Navigate to your gallery. Example: if you uploaded in a subfolder named "zenphoto" navigate to www.yoursite.org/zenphoto/. Setup.php will run. (if it somehow does not, please navigate directly to www.yoursite.org/zenphoto/zp-core/setup.php.). Info about the required permissions if you run into issues.
- Enter the MySQL credentials (you get them from your provider) and make sure everything checks out.
Note on fresh installs with Zenphoto 1.6+: You can only enter database credentials once via the setup form. Once the config file is created and you have wrong credentials you have to enter them in the file itself via FTP. We only consider it a "fresh" install as long as there is no config file present.
- Then click GO!
Note on fresh installs with Zenphoto 1.6+: As soon as setup is started the site is in maintenance mode to block any outside access disturbing it.
With anything after ZenPhoto 1.1.3, upgrading is super easy! These instructions apply of course also if you want to install a support build.
Each new version of Zenphoto provides new capabilities. We try to provide forward migration, but we do not test arbitrary upgrades steps.
The only sequence we can guarantee to work is upgrading from the previous feature release and of course within from support release to support release of the same feature release. Even then you should check the release posts in case bugfixes do cause some other changes.
If you are skipping any significant number of releases, check the support forum for upgrade issues.
Also never upgrade individual files from the Zenphoto package only unless we have told so. As changes often influence several parts in the code, this may brake your site.
- Check if your server matches the requirementts
- If you use 3rd party tools like themes or plugins, check if updates are available. Old 3rd party themes and plugins may not be compatible with newer Zenphoto versions. Recommendation: If your site is an important live site to you or your client, always first test an upgrade – especially bigger version jumps – on a staging site either on the live server or in an local development environment (e.g. using WAMP, XAMPP, MAMP) before performing the update on the live site. Then you can test if evrything works as expected without harming your live site in case anything goes wrong. Don't forget to review your logs for possible issue.
- Backup your MySQL database. You can use Zenphoto's own utiltiy "backup_restore" for the database content but for a full backup of the database use a tool like phpMyAdmin.
- Log into your existing site to be sure you know your Zenphoto user/password (you need admin rights to run setup on upgrades!). Password recovery is not available during an upgrade!
- Be sure to backup customized themes or plugins – 3rd party plugins should always be in /plugins only anyway! – or any other customized files before replacing anything! Or selectively upload the official themes especially (see above!)
- Download the latest version of Zenphoto.
- Close your site for the public using the included site_upgrade plugin during the upload and setup process.
- Upload the following files and folders. Make sure your FTP client overwrites/replaces the folders. Depending on your FTP client it may ask if it should join/merge/update or replace folder contents. Some FTP clients tend to mess up overwriting, especially folders with lots of files, so good practice is to delete the old folders first and then upload the new files:
- /themes (or actually just the four official themes within - again, backup if you have custom or customized themes within this folder!)
- /zp-core (especially here make sure that really the entire content is replaced so that no orphaned files because of removed or renamed ones are kept)
- Make sure the .htaccess file is writeable. If you do not have a .htaccess file, you will be given the opportunity to create one during setup. Given that your server supports .htaccess/modrewrite in the first place of course.
- Once the files are uploaded, navigate to www.yoursite.org/zenphoto/ (if you have installed Zenphoto within the folder zenphoto). Setup.php will run. If it somehow does not, please navigate directly to www.yoursite.org/zenphoto/zp-core/setup.php. Info about the required permissions if you run into issues.
- Make sure everything checks out, and click go!
- Follow the instructions.
Note on installs with Zenphoto 1.6+: As soon as setup is started the site is in maintenance mode to block any outside access disturbing it.
- You're done! Enjoy.
Note: If you are upgrading to a support build from the GitHub repository to help testing, always upload the complete package, never just indiviual files unless you have been told otherwise by the developers. Also make sure setup is run manually. Avoid testing support builds on important live sites.
- Moving and changing existing installations
- Re-running setup files
- Content of the Zenphoto package
- Versioning (Release number info)
- Builds (Support build vs development build)
Please also visit the Troubleshooting guide.
This text by www.zenphoto.org is licensed under a Creative Commons Attribution-ShareAlike 3.0 Unported License.
Code examples are released under the GPL v2 or later license