Installation, Upgrading and Requirements 08 August 2008 / Updated: 15 February 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. (technically Zenphoto can do this automatically but virtually no host allows this!)
- 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.
- Then click GO!
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!). 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.
- 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 existing installations
Note that if you are planning both a move of your installation and an update to a new version you should separate these steps. When you upgrade, setup will migrate your database to be consistent with the current version of Zenphoto. If you do some thing like restoring your database to what existed for a previous version of Zenphoto you have potentially compromised everything in your installation.
So, bottom line, if you use MySQL to backup and restore your database, be sure you do so with the same version of Zenphoto running. Zenphoto does provide a backup/restore facility that is able to deal with many of the migration issues. But it is still recommended that you do your restore on the same version of Zenphoto that created the backup because you will not know if it can handle the migration until the restore.
More detailed information on the article "Moving and changing existing installations".
Re-running and re-uploading setup files
Sometimes Zenphoto will request you to re-run the setup scripts and doing that lists files that might be a problem. This is a security measure if Zenphoto detects a change on your install. These can be files whose file time is off to the rest of them.
This can happen if you upload theme files two hours after the core files so all is fine. But it could also be a hack of a file.
It also triggers if there are files that should not be there as it checks its internal file catalog. This is nothing but a warning. Setup offers to delete the marked files but you don't need to. It has to assume you know about your install and what files should be there.
This might also be triggered if server software (e.g. MySQL or PHP) on your server has been updated.
Re-running Setup on Zenphoto 1.4.6 or newer
Using the <path to your install>/zp-core/setup.php link should unprotect the setup scripts and run them.
On Zenphoto 1.5 or newer setup files are automatically protected after setup ran.
Or you can use the utility button on the admin overview page to unprotect the scripts:
After clicking this a new button will appear that allows you to run setup:
Re-running Setup on Zenphoto versions older than 1.4.6
On older Zenphoto versions you may need to re-upload the setup scripts. Here the setup scripts were not protected but indeed deleted. In that case you find them in the release package: /zp-core/setup.php (folder with several files). Re-upload that folder and navigated to <path to your install>/zp-core/setup.php to re-run.
To operate Zenphoto efficiently, you need (our setup script will also tell you about possible problems):
- A web server with at least 25Mb of free space (plus free space for images and cache files)
- Apache* (it may work without problems on other server systems like nginx, IIS or lighttpd but we have not tested these.)
PHP 5.6+ (7.2+ strongely recommended) – it may still work with older versions of PHP below 5.6 but we actually don't test and won't fix any related issues.
- NOTE: Zenphoto is not compatible and tested with PHP 8 yet
- It is recommend that you have the following PHP extensions and settings:
- One of these graphics libaries for image resizing:
- GD graphics library (usually built in on servers)
- Imagick graphics libary 6.3.8/Imagick 3.0.0+
- safe mode off (recommended)
- magic_quotes off (recommended)
- register globals off (required)
- gettext extension (optional, required if you plan to use Zenphoto's translation/multilingual capabilites - note that your server must have the locales for the languages installed you intend to use)
- mbstring extension (recommended if you are using a none English language with lots of special characters)
- tidy extension (recommended to properly truncate text content containing HTML)
- cURL extension (recommended)
- mod_rewrite (recommended) – Note that non Apache servers not supporting htacess may require extra setup
- One of these graphics libaries for image resizing:
MySQL 5+* (5.5.3+ recommended) – MySQL 4 is not supported - Compatible MariaDB versions should also work but are not tested specifically.
- Appropriate user account rights. (Setup will note if you do not have sufficient rights.)
- UTF-8 table and field collations
*Zenphoto is developed and tested on Apache environment.
- Internet Explorer 7 or newer (we really recommend using the latest but never 6 or below…!)
- Safari 5.1 or newer
- Google Chrome (current version)
- Opera 12.1/Opera 19 or newer
Probably a lot does work in older browser as well but we don't and can't really test it. We therefore recommend to use the latest browser version possible on your system.
The Zenphoto package consists of these root items after extracting. This is what you need to upload. Note: Your FTP program should be set to merge files within the package folders with folders in an existing insallation. Setup will prompt you if any old files should be removed.
- .gitattributes** – An invisible file from the Git version control on GitHub.
- .gitignore** – An invisible file from the Git version control on GitHub.
- albums* – This folder contains the full images, videos etc. within subfolders (= the albums) after uploading.
- contributing.md – This is just a markdown formatted text file with info link about how to contribute to the Zenphoto project. No need to upload this when installing.
- index.php – This is the "front-end" script for Zenphoto. All references to the gallery go through it. Often referenced as the "root index file".
LICENSE** – The Zenphoto GNU General Public License.
- plugins – This is the place to store 3rd party and custom plugins, custom watermarks, etc.
- README.md** – This is a file from GitHub that just contains the intro text of the repository.
- themes – As you may guess this contains the themes. Four standard themes are included.
- uploaded* – This is the folder the (non gallery) file manager stores uploaded files.
- zp-core – This is the Zenphoto core that runs everything.
- zp-data* – This stores your zenphoto.cfg file, the Zenphoto setup, security and debug log files.
During setup two additional folders are created:
- cache -- The processed thumbnails and sized images are stored here.
- cache_html -- Static files from RSS feeds, the static HTML cache plugin or the sitemap-extended plugin are stored here - if the given option or plugin is enabled naturally.
After running setup a .htaccess file and a robot.txt file will be created in the root if you select the related options. You may need to adjust the robots.txt file to your liking as it is set very strict by default.
* These folders are empty in the package.
** These files/folders are not used by a running installation and do not need to be uploaded.
Release number info
Please note the following definitions on what each of the digits in our release numbering signifies.
- Change in the first digit of the release represents a major release (e.g. 1.x to 2.x)
- Change in the second digit represents a feature release (e.g. 1.3 to 1.4)
- Change in the third digit represents a support release with only bug fixes or smaller features that should not cause any trouble (e.g. 1.4.3 to 1.4.4)
- Change in the first digit of the release represents a major change (e.g. 1.x to 2.x)
- Change in the second digit represents a major feature release (e.g. 1.3 to 1.4)
- Change in the third digit represents a minor feature release with new features and bugfixes (e.g. 1.4.3 to 1.4.4)
- Change in the fourth digit represents a support release with only bugfixes (e.g. 22.214.171.124)
In the case of support releases we expect no compatibility issues with running sites. For all other releases you should review the release announcement to get an idea of possible incompatibilities with third party themes and plugins.
Support build vs development build
There are two builds on the Zenphoto download page additionally to the official release:
1. Support build
This is also called the master in GitHub terms and represents the next official bugfix/maintainance release. If the current official release is 1.5.7 the support build has generally the version 1.5.8b (b for beta) and continously gets all the fixes to become 1.5.8 later on.
It may also have a higher version like 1.6b depending on the developlemt plan.
Generally the support build will be compatible with the official release but it cannot always be guaranteed because of bugfixes and other changes involved. Especially if security fixes require specific changes.
If you report any issue with the official release we often ask you to try this build to be sure things are really fixed.
2. Development build
Currently there is no development build. If there is this is the development for the next feature release. So if 1.4.4 is the current release stream this will become 1.5.x and will get all the new features we make up.
Sometimes we ask you to try this as well so we can make sure new features or other improvements are done right. Best don't try this on an important live site as this is work in progress naturally.
Please note: If we point you to test one of these builds please do so as this helps us to make the next release better. We cannot test all possible server environments so this helps us a lot. Installation is done like regular updates
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