User guide

Installation, Upgrading and Requirements

    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.

    Installation

    1. Download the latest version of Zenphoto.
    2. Extract the files to your computer then upload all files and folders as listed above to your web directory via FTP. You can upload them either in the root of your webspace or within a subfolder.
    3. Create a MySQL database if you haven't already one.
    4. 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.
    5. Enter the MySQL credentials (you get them from your provider) and make sure everything checks out.
    6. Then click GO!
    7. ENJOY!

    Upgrading

    With anything after ZenPhoto 1.1.3, upgrading is super easy! These instructions apply of course also if you want to install a nightly 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. 

    1. Backup your MySQL database (use the database backup tool on the Zenphoto overview page for example).
    2. Log into your existing site to be sure you know your Zenphoto user/password. Password recovery is not available during an upgrade!
    3. Be sure to backup customized themes or plugins or any other customized file before replacing anything! (see above!)
    4. 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:
      1. index.php
      2. /themes (or actually just the six official themes within - backup if you have custom or customized themes within this folder!)
      3. /zp-core
    5. 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.)
    6. 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.
    7. Make sure everything checks out, and click go!
    8. Follow the instructions.
    9. 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.

    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

    The setup scripts are automatically protected for security reasons after a successful install or upgrade. 

    Sometimes Zenphoto will request you to re-run the scripts. This is a security measure if Zenphoto detects a change on your install. This might also be triggered if server software (e.g. MySQL or PHP) on your server has been updated. Using the ...zp-core/setup link will normally unprotect the scripts and run setup. If not you may need to re-upload the setup scripts.

    You find them in the release package:

    /zp-core/setup.php/zp-core/setup (folder with several files)

    Requirements

    Server requirements

    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 settings:
      • 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)
    • MySQL 5+* (5.5 recommended) – MySQL 4 is not supported
      • 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.

    Browser requirements

    The Zenphoto backend uses the JavaScript framework jQuery  – currently in Version 1.x – as the standard libary for all sorts of things so we basically can support what it does. That would be roughly:

    • 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.

    Content of the Zenphoto package

    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** – A file from the Git version control on GitHub.
    • .gitignore** – A file from the Git version control on GitHub. 
    • /albums* – This folder contains the full images, videos etc. within subfolders (= the albums) after uploading. 
    • /cache* – Here the cached processed images like thumbnails or sized images are stored
    • /cache_html* – Here cached static files from RSS feeds, the static HTML cache plugin or the sitemap-extended plugin are stored - if the given option or plugin is enabled naturally
    • /doc_files** – This contains a PDF with a database quick reference, a readme.html file and the license text.
    • 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".
    • /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. Six 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.

    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 paradigm change (e.g. 1.x to 2.x)
    • Change in the second digit or third represents a feature release (e.g. 1.3 to 1.4 or 1.4.2 to 1.4.3)
    • Change in the fourth digit represents a support release with only bug fixes (e.g. 1.4.3 to 1.4.3.1)

    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.3 this gets continously all the fixes to become 1.4.4.4 later one. 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.x is the current release stream this will become 1.4.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 Zenphoto guide

    Creative Commons LicenseThis text by www.zenphoto.org is licensed under a Creative Commons Attribution-ShareAlike 3.0 Unported License.

    For questions and comments please use the forum or discuss on the social networks.

    Related items