Gallery 2

Welcome to Gallery 2. This is the first official release of Gallery 2.0, code named “Unpossible!”. 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. Before you do that though, you really should read the When should I use it? section. 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 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

When should I use it?

Gallery 2 is a stable and secure environment for you to store your photos online and share them with your friends. Use it to manage all of your media with confidence. It is reliable, modular, portable and intuitive.


While Gallery 2 has not yet been subjected to a rigorous security audit, it has been widely used for over a year during the alpha, beta and release candidates phases. Only minor security flaws have been identified during this time, and they were quickly addressed. We take security very seriously, so 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.0 (Unpossible!) -

  1. Updated version of the Siriux theme.
  2. Several bug fixes.

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 three 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.
  3. Database - Right now we support MySQL, PostgreSQL and Oracle. MySQL is generally faster than PostgreSQL. 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};

  4. Graphics Toolkits - Gallery 2 works with NetPBM, ImageMagick, GD or GraphicsMagick. They’re all almost equally good, though some say that NetPBM has slightly better quality and that ImageMagick is slightly faster than NetPBM. GD cannot do image rotation. GraphicsMagick and ImageMagick are very similar. GD can be very fast, but it will also use a lot of memory so it may cause you to run into predefined server limits. It is also compiled into PHP by default if your PHP is 4.3.0 or more recent, however it may not have support for all image types (e.g. it might not have JPEG support). If the binaries for NetPBM and ImageMagick are installed in default, or standard, locations then Gallery 2 will auto-detect them during installation. It won’t cause any harm to enable all of these toolkits—in fact you’ll get the widest file type support if you do so.


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.

  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.

  1. 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.
  2. 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.
  3. 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.)
  4. Enjoy your new version of Gallery 2.

Getting Help

If you have problems, you should start by looking in the Gallery 2 FAQ and in the Gallery 2 Support Forum on the Gallery Website. Search the forum to see if somebody else has posted a similar problem and maybe there’s an answer there, otherwise start a new topic to get help. If the problem seems like a bug in the Gallery 2 software you can file a bug in our bug tracker on SourceForge. Please read our tracker guidelines before filing a bug so that we can cut down on the number of spurious reports. If you're unsure whether to file a bug you can always post in the forums first and we'll ask you to file a bug if needed. If you want to chat in real time, you can talk on our user-to-user irc support channel, #gallery-support on

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

  1. Theme upgrade - In beta-4 all layouts have been replaced with the new theme system. During the upgrade process the layout setting on all albums is cleared and the site-wide default theme is set to matrix. You'll have to reselect the default theme and any album specific settings to restore the layout configuration in place prior to this upgrade.
  2. Performance - There are still some tweaks that we can make to have it go faster, stay tuned!
  3. Login Problems - Before beta-4 there were known login / session problems. As a consequence of our fix for this problem, you and all your Gallery users have to delete old GALLERYSID cookie(s) in your browser if Gallery seems to ignore login requests.
  4. View names - In beta-4 the naming convention for views changed from using a colon separator to a period (core:ShowItem is now core.ShowItem). All Gallery code has been updated but there are a few places you should check to make sure your site is up to date:
  5. Multisite config.php - The multisite system changed in beta-4 and old style multisite config.php files are no longer supported. Follow these steps to move your sites to the new system:

Advanced Topics

Unit Tests - Gallery 2 was designed using Extreme Programming methodologies. This means that we have a ton of unit tests that help us make sure that the code is behaving as it should. 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 - See this forum topic for the status of the integration modules to embed Gallery 2 in various applications. This documentation explains how to setup an integrated environment or build the integration module for a new application.

This page is valid XHTML 1.0 Gallery 2.0 G2.0: Unpossible!

$Id: README.html,v 2005/09/13 08:02:11 bharat Exp $