Installation, Upgrading and Requirements Aug 08, 2008 / Updated: Feb 02, 2015
NOTE: There are a number of 3rd party install scripts available for Zenphoto (and other CMS). Scripts such as SimpleScripts version 3 execute each of the necessary Zenphoto setup steps and should produce indentical 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. 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 that but virtually no host allows this!)
- 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.
Important note: 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. You should check the support forum for upgrade issues if you are skipping any significant number of releases.
- Backup your MySQL database (use the database backup tool on the Zenphoto overview page for example).
- 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 or any other customized files before replacing anything! (see above!)
- Download the latest version and upload the following files.
Since FTP clients tend to mess overwriting, especially folders with
lots of files, best practice is to delete the old files first and
then upload the new files:
- /themes (or actually just the five official themes within - backup if you have custom or customized themes within this folder!)
- 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 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.
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 then 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.
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* / nginx* (it may work without problems on other server systems like IIS or lighttpd but we have not tested these.)
- PHP 5.2+* – It may work with older versions of PHP 5 but we have not tested with them. It will not work with PHP 4.
- It is recommend that you have the following PHP extensions and
- One of these graphics libaries for image resizing:
- GD graphics library (usually built in on servers)
- Imagick graphics libary 6.3.8/Imagick 2.1.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)
- mbstring extension (recommended if you are using a none English language with lots of special characters)
- One of these graphics libaries for image resizing:
- MySQL 5+* (5.5 recommended) – MySQL 4 is
- 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 this 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.
- 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. Five 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 change (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 (e.g. 1.4.3 to 1.4.4)
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 a feel for the degree that incompatibilities may occur 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. So in case of say 1.4.4 this continously gets all the fixes to become 1.4.5 later on. This does not get any new features or serious changes so it should be fully compatible to the current release.
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
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.