Gallery 2

Welcome to Gallery 2. This is the official release of Gallery 2.1, code named “Blackjack”. Please read through this document carefully before installing Gallery 2 and before asking for help. We have taken care to try to answer as many of your questions here as possible. If you don't read this and have problems, we may refer you back to this document as a first resource.

Quick Start

If you’re impatient like us, you just want to get going. The odds are that your system is all set to handle Gallery 2 so just skip right to the installer and start clicking. It should walk you through everything you need to get going. If you hit a snag, please come back here and read more before asking questions! Enjoy.

What is Gallery?

Gallery is a web based software product that lets you manage your photos on your own website. You must have your own website with PHP and database support in order to install and use it. With Gallery you can easily create and maintain albums of photos via an intuitive interface. Photo management includes automatic thumbnail creation, image resizing, rotation, ordering, captioning, searching and more. Albums and photos can have view, edit, delete and other permissions per individual authenticated user for an additional level of privacy. It's great for communities - give accounts to your friends and family and let them upload and manage their own photos on your website!

System requirements


The Gallery team retained Paul Mutton of Intershot Limited to do a complete security audit of Gallery 2.1 Release Candidate 1.

"The Gallery installer and Gallery application were subjected to a manual web application security test. It is important to note that such tests cannot be exhaustive and may not discover all vulnerabilities. All tests were carried out against a standalone installation of Gallery - no integrated installations were tested (e.g. with phpBB or phpnuke). The security of external tools used by the Gallery application, such as graphics toolkits, were not included in this test. No denial of service attacks were carried out against the application server."

The development team resolved the security issues raised by Intershot and other auditors during the release candidate phases.


The Gallery project treats security issues very seriously. If you find a security flaw, do not hesitate to email us at:

security AT

What’s new in this release?

Over three years of design and development have gone into making Gallery 2 the best online photo management product available. We have made it easy to add new features while keeping them in separate modules so that you can customize it to only have the ones that you want. For those of you who like standards, we have strict XHTML compliance but give plenty of power to our themes so that you can make it look the way that you want. It's a powerful application and you're in the driver's seat.

Highlight of changes in Gallery 2.1 (Blackjack) -

  1. New Ratings module allows users to vote for their favorite photos.
  2. New RSS module provides syndication of your Gallery's content to the world, so users can track content updates.
  3. New Floatrix theme based on our Matrix theme, with a collapsible sidebar and tableless design.
  4. New module to support hidden items and albums. Hidden items are restricted from guest users until accessed by the direct URL. Migrate module now imports hidden items from G1 as hidden in G2 if this module is active.
  5. New module to support password protected items and albums. Passwords are complementary to the G2 permission management. Passwords are impersonal while the G2 permission system handles access and rights for specific users and user groups.
  6. New Reupload module allows replacing an image file while keeping the title, description, comments, etc.
  7. New Permalinks module works with the URL Rewrite module to create short URLs using just the album name, as in Gallery 1.x.
  8. New Linkitem module creates links to other albums or external URLs.
  9. New module to import albums from Picasa.
  10. New module to support Google Sitemaps.
  11. New module for retrieving id3 tag information.
  12. New link in comments module to view all recent comments. Also an option to require captcha for posting anonymous comments.
  13. New option to apply album and theme settings recursively to all subalbums.
  14. URL Rewrite module now supports IIS (isapi rewrite) and pathinfo.
  15. Captcha module has an improved "medium" security level and now unifies configuration in captcha site admin for all modules making use of validation.
  16. Print modules
  17. Permission support in cart module to control which users and which items may be used with the cart.
  18. PublishXP module now supports add-options such as watermarks and applying size limits or quotas.
  19. Upgraded bundled EXIF library to Exifixer 1.5 which fixes reading of EXIF data from many cameras and image processing tools. Also updated the module to make GPS fields available and to read EXIF data from raw image files.
  20. New option in ffmpeg module to watermark thumbnails for movie items with a film reel image on each side, to better distingish movies from photos. Support for recent versions of ffmpeg binary.
  21. Support for recent versions of dcraw binary.
  22. Added WMF and TGA image format support in ImageMagick module.
  23. Improved cross-browser support in ImageFrame module.
  24. Several updates and new options for Hybrid theme.
  25. New settings and improved admin interface for Siriux theme.
  26. Localization updates
  27. User Interface updates in installer/upgrader based on a review by
  28. New performance section in site admin for configuring optional page caching.
  29. New maintenance mode to redirect visitors while upgrading or configuring the site.
  30. Multisite installs can now use the tools in lib/support.
  31. Sessions are now stored in the database and no longer in files. And guest users don't get a session anymore unless they add items to the cart, choose a non-default language or do something else that requires a session.
  32. New development tool: sample module creator in lib/tools/creator.
  33. New option to run external programs at lower priority to reduce load on shared webhosting servers.
  34. Support for DB2 database.
  35. Minor updates to support PHP 5.1.
  36. Embed API is now versioned (for compatibility checks) and initialization parameters have been simplified.
  37. Many code updates, restructuring and API changes with the goals of improving performance and making smaller/simpler/cleaner code.
  38. Lots of bugs fixed.

Highlight of changes in Gallery 2.0 (Unpossible!) +

Highlight of changes in Gallery 2 RC 2 (kthxbye) +

Highlight of changes in Gallery 2 RC 1 (+5 Insightful) +

Highlight of changes in Gallery 2 Beta 4 (Flippin' Sweet!) +

Highlight of changes in Gallery 2 Beta 3 (Bingo!) +

Highlight of changes in Gallery 2 Beta 2 (Holy Hand Grenade) +

Highlight of changes in Gallery 2 Beta 1 (Dark Fibre) +

Highlight of changes in Gallery 2 Alpha 4 (Nice Commits) +

Highlight of changes in Gallery 2 Alpha 3 (Farva) +

Highlight of changes in Gallery 2 Alpha 2 (Grand Theft Photo) +

Highlight of changes in Gallery 2 Alpha 1 (Cowbell) +

Choosing a package

You can choose from four different packages:

You get to pick and choose which modules you activate, so even if you download a package that has more modules than you need you can always choose not to activate the ones you don't want. You can also activate a module and test it out for a while, then later deactivate and deinstall it. You can also delete any modules/themes that you're not using if you want to save space.

All of our modules and themes are available separately so if you install a smaller package and then later on decide that you want to add more functionality you can download just the modules/themes that you want and install them yourself.

Download Gallery packages, modules and themes from the Gallery Download Page.

Preparing to install

  1. Latest Version - There are four ways to get the code.
  2. Storage - Create a directory for gallery to store photos. This must be writeable by the web server, but for security reasons we suggest that you do not put it in the web root. If you put it in the web root, then anybody can get directly to your images with their web browser which circumvents Gallery 2’s security.

    Unix Example

    $ cd $HOME
    $ mkdir g2data
    $ chmod 777 g2data

    Windows Example

    C:\> mkdir g2data

    In the Unix example, you may note that modes of 777 on your g2data directory are not all that secure. However, making it more secure depends on how your system is configured. Talk with your system administrator about ways to change the permissions on that directory to make it so that Gallery can still write to the files but that others can’t. Refer to the Gallery 2 Security Guide for more information.
  3. Database - Right now we support MySQL, PostgreSQL, Oracle and DB2. MySQL is generally faster than PostgreSQL. Oracle and DB2 are barely tested. We require you to create the database yourself. In our examples below, we’ll be creating a database called gallery2. You can use any database name that you choose.
    Grant all required privileges to your database user. This includes but is not confined to: CREATE TABLE, ALTER TABLE, DROP TABLE in the gallery2 database; SELECT, INSERT, UPDATE, DELETE on all (gallery2) tables in the gallery2 database; CREATE INDEX and some other privileges that are specific to the different database management systems. CREATE/DROP DATABASE and the ability to GRANT privileges to other database users are not required.


    $ mysqladmin -uroot create gallery2
    $ mysql gallery2 -uroot -e"GRANT ALL ON gallery2.* TO
      username@localhost IDENTIFIED BY 'password'"


    $ createdb gallery2 -E UNICODE

    If it complains that UNICODE is not a valid encoding name, then try:
    $ createdb gallery2 -E SQL_ASCII

    If it complains about that, too then try:
    $ createdb gallery2


    $ create database gallery2 {additional parameters};


    $ db2 "create database gallery2 using codeset utf-8 territory us pagesize 32 k"

  4. Graphics Toolkits - Gallery 2 works with many different toolkits (NetPBM, ImageMagick, GD or GraphicsMagick). You need to activate at least one or you won't get any thumbnails, but there's no limit on how many you can have. In fact, more is better because they can work together. Here are some interesting points about the main supported toolkits (mostly reported by users, your mileage may vary). Limitations:


Gallery 2 is a web application and must be installed on your web server in order for you to use it. If you've unpacked it on your desktop, you will have to upload it to your server as part of the install process. Then you can configure it using your web browser.
As an alternative to the lengthy upload via FTP, take a look at the Gallery 2 Pre-Installer.

  1. Upload - Copy the Gallery 2 files to a directory on your webserver. There are several alternatives for this step: Note: After uploading, you should close this version of the README and browse to the version that you just uploaded. That way all the links in this document will point to the right places in your Gallery 2 install.
  2. Begin Installing - Open up your web browser and browse to the install directory. Gallery 2 will walk you through the process of validating that your system is properly configured and will set everything up for you.
  3. Authenticate - You will be asked to create and save a small text file in order to authenticate. You may not proceed until you do this. That’s how Gallery 2 knows that you’re authorized to use the installer.
  4. System Checks - The installer checks your system to make sure that it will support Gallery 2. Make sure that all checks are successful!
  5. Installation Type - Gallery can support multiple independent sites with a single installation of the code. Here you will select a standard single install or the location of a new multisite install. There is more information about multisite in the Gallery Codex.
  6. Storage Setup - Read the instructions on the installer to set up a storage location for Gallery 2. This is where Gallery 2 will store all of your images, as well as other cache information.
  7. Database Setup - Select your database type and enter your database authentication information. If this is not your first Gallery 2 installation and there are still some remains of the old installation, it will check the state of the installed version and offer a clean install option which will delete all your data in the storage directory and in the database. If the installed version seems to be fine, it will also offer to reuse the existing database tables. Select this option if you did not start the installer with the intent to start from scratch.
  8. Admin User Setup - You are prompted for an administrator username and password. Type in a password and type it again to validate it. The full name and the email address are optional. But entering an email address is highly recommended. Once you’re finished, click ’Create’ to create the admin user for this installation of Gallery 2.
  9. Create Config File - Gallery 2 will create the config.php file in your Gallery 2 directory. This contains all the answers you’ve provided in the installer and is necessary for Gallery 2 to function properly. At this point, there’s also a sanity check to prevent you from damaging your Gallery install by running the installer when you should rather have started the upgrader.
  10. Install the Core module - Here’s where we create all the database tables and initial users and albums to get you started. Unless something goes wrong, there’s nothing for you to do here.
  11. Install other modules - Gallery 2 has lots of different modules that provide useful functionality. Choose which ones you want to use. You can always go to the Site Admin page later on to install, activate, deactivate or uninstall modules, so it’s ok to experiment here.
  12. Check Security - Gallery 2 walks you through the process of locking down your new config.php.
  13. Finished! - Congratulations! You have successfully installed Gallery 2!

Using your new Gallery

  1. Log in - Once you’ve successfully got Gallery 2 installed, you should start by logging in as the admin user that was created for you at install time. The admin user has special privileges that you’ll need in order to administer your new Gallery 2.
  2. Activate Graphics Toolkits - Click on the Site Admin link then the Modules link to see the module list. Install, configure and activate one of the NetPBM, ImageMagick, or GD modules. You can activate as many of them as you want (more is better, here).
  3. Add photos - Browse back to the top of your new Gallery 2 and click on the Add Items link. This will bring up a page with a few different upload options (at least 3, more if you have other upload modules installed). Select the one you want and try adding a new photo to your album. If all goes well, you should see the new photos in your Gallery!.
  4. Add an album - You don't want to put all of your images into the top level of your Gallery 2, so you should try creating a new album. Browse back to the top of your new Gallery 2 and click on the Add Album link from the left side of the page. This will give you a form where you can enter information about the new album you want to create. Fill it out and click the Create button. Now try adding images to that album instead, or select the Move Photo link from under any of the images you added earlier and move them into this new album.
  5. Import Gallery 1 albums - you can easily import albums from Gallery 1. It won’t cause any harm to your Gallery 1. Just go to the Migration Page and enter the path to your Gallery 1 albums directory and then follow the instructions.
  6. Plenty to do and see! -

Updating your Gallery 2 Installation

Updating is quick and easy and should not lose any of your data.


There are changes in Gallery 2.1 that cause it to be incompatible with modules and themes from Gallery 2.0. All modules and themes released by the Gallery project have been updated to work with 2.1, but if you're using third party modules/themes you may find that they do not work with the 2.1 release.

If you're worried, you can either deactivate any third party modules before beginning your upgrade, or find and use the latest version of the third party module.

Gallery 2.1 will detect if you're missing the appropriate version of a necessary module and will abort the upgrade before making any changes so you will not lose any data.

Third party modules and themes:

  1. If you have a busy site, consider putting your Gallery in maintenance mode before updating the code and performing the upgrade. This gives visitors a message that the site is temporarily offline, rather than showing everybody the upgrade page. Edit your config.php file to activate maintenance mode. This feature is new in 2.1, so it is not available in an upgrade from 2.0.x.
  2. Download the latest code for any active third party modules that you're using, or deactivate them. If in doubt, deactivating is safe.
  3. Get the latest code and unpack it over your existing copy of Gallery 2. Keep your existing config.php in place, and don't touch your (g2data) data folder or the database. If you're using CVS, you can just do "cvs update -Pd" at any time. Alternatively, you can also use the Gallery 2 Pre-Installer to get the latest code onto the webserver.
  4. If you use a PHP accelerator / cache (e.g. Turk mmCache, Ioncube PHPA, eaccelerator, Zend Studio, etc.), flush (clear) the cache of the accelerator. Omitting this step can sometimes lead to errors during and after the upgrade process.
  5. Browse to the upgrader and follow the instructions there. Make a backup of your data (g2data folder and the database) when it tells you to! Should you lose your data due to a bug in the upgrader, the first thing we're going to tell you to do is to restore from your backups! (Then we'll probably ask you to help us reproduce the bug.)
  6. Enjoy your new version of Gallery 2.

Getting Help

There are many resources available to you if you're having problems with Gallery:

Remember – reporting bugs is good. Even if you think it’s silly, go ahead and report it. We can always close the bug or refile it (please don’t be offended in this case) but it’s harder to find bugs than it is to fix them so we’re counting on you to help us with the finding part.

Known Issues / Bugs

Check our Known Issues list and Bug Tracker for information and some workarounds for known problems.

Advanced Topics

Unit Tests - Gallery 2 was designed using Extreme Programming methodologies. This means that we have over 2,000 unit tests that ensure code quality. If you want to help us out, you can try running the unit tests and report back to us if any of them fail.

Note - these tests shouldn’t change your Gallery 2 settings at all, but if they fail, they may leave things in a weird state. Be warned that there's a slim chance that you might have to ditch your Gallery 2 data and start over if something catastrophic happens.

For Themers - There is now some theme documentation that you should read if you want to change the look of your Gallery 2 by customizing an existing theme and its templates or by creating your own theme.

Localization - If you’re interested in localizing Gallery 2 into another language, you can review the current state of localization and then read the localization how-to and get started. Submit your localizations early and often - no need to wait until you’re entirely done.

For Developers - We've gotten started on some developer documentation that you should read if you want to start hacking on Gallery 2. Some of the information is a little bit out of date or in early drafts, but it's a start.

Embedding - To learn more about embedding Gallery 2 into your website and about existing integrations in content management systems, portals, blogs etc. please see Gallery 2 Embedding.

This page is valid XHTML 1.0 Gallery 2

$Id: README.html,v 2006/04/13 17:16:44 bharat Exp $