Difference between revisions of "Gallery2:FAQ" - Gallery Codex
Personal tools

Difference between revisions of "Gallery2:FAQ"

From Gallery Codex

(Beta/Develop Specific)
m (I use NFS and gallery isn't working, is there a solution?)
Line 131: Line 131:
Permissions are handled on an item by item bases, not an album by album basis. Just because "album01" is private, doesn't mean that "album01/album02/image3" is also private. This is by design and intentional, BUT the problem is in the interface which does not mention or explain this in any way. You can find the bug report here if you would like a better / different description.  
Permissions are handled on an item by item bases, not an album by album basis. Just because "album01" is private, doesn't mean that "album01/album02/image3" is also private. This is by design and intentional, BUT the problem is in the interface which does not mention or explain this in any way. You can find the bug report here if you would like a better / different description.  
===I use NFS and gallery isn't working, is there a solution?===
===I use NFS and Gallery isn't working, is there a solution?===
By default Gallery 2 uses flock for locking and this is known not to work over NFS. Go to Site Admin / General and switch to database locking instead.
By default Gallery 2 uses flock for locking and this is known not to work over NFS. Go to Site Admin / General and switch to database locking instead.

Revision as of 11:48, 6 August 2005





All credits on this (beta) FAQ are due to FryFrog, text is taken from G2 FAQ thread.

Getting Gallery2

Where can I get the latest version of G2?

You can download the latest official release of G2 from the sourceforge download page. Nightly snapshots are available on galleryupdates.jpmullan.com and are reasonably stable.

How can I get Gallery2 on my webserver?

Copy the Gallery 2 files to a directory on your webserver. There are several alternatives for this step:

  • Ideally, you can use cvs to install and update your Gallery 2 installation directly on the server. But this option is only available if you have command line access to the server (ssh/telnet).
  • The next best alternative is to upload the gallery2.tar.gz or gallery2.zip archive via FTP or another method. Then unarchive / extract the archive in the command line (ssh/telnet) or with a miniature PHP script with the command ’tar -xzf gallery2.tar.gz’ for the .tar.gz archive or ’unzip gallery2.zip’ for the .zip archive. Some webhosting companies offer a control panel with a web file-browser which is capable of extracting / unarchiving archive files. It’s worth a try to check if this option is available.
  • If you have neither of these options, you have to upload the complete contents of the Gallery 2 archive to the webserver with an FTP program. This will take a lot of time and is error-prone. In this case, pay special attention to the ’System Checks’ step of the installer and make sure that there are no missing or modified files.

Once I have G2, where do I begin?

The BEST place to start is /gallery2/README.html. If you wish to jump ahead and start the install, you can point your browser at /gallery2/install/ instead. If it's your first time, you will need to visit the README.html in order to find database setup instructions.

Does G2 have any special requirements?

Gallery 2 requires many of the same things that G1 required. A web server, php and some graphics manipulation programs. You probably already know these things... but there is ONE new requirement: a database. Right now, there is support for MySQL 3,4, PostgreSQL and Oracle 9/10. Of course, the other requirements are a web server (apache, iis, zeus?), php (4 or 5) and some grahpics manipulation packages (netpbm, imagemagick, ffmpeg, gd). Space for the images is probably one of the more obvious requirements :)

How can I get the latest version of Gallery2?

There are two ways of keeping current, using CVS or using nightly builds. Chetan Sarva and Jesse Mullan both offer nightly builds. The instructions for using CVS can be found here . You can also find instructions for using WinCVS here .

To get the CVS version of Gallery, see the next FAQ item.

Should I use nightly builds or CVS?

That is up to you, I would suggest CVS if you are comfortable working with it or don't mind learning. Once you get the original source from CVS, updating is as simple as going to your G2 directory and typing "cvs -z3 update -Pd" (-P prunes empty dirs and -d deletes files that were removed). There are a couple other options you can use if you wish.

# cd /path/to/gallery2/ 
# cvs -z3 update -Pd 

How to upgrade Gallery2?

Updating is quick and easy and should not lose any of your data. But better be save! Make a full backup of your gallery and your g2data directories and your database. Although it is a proven concept, you better be save than sorry.

  • 1. Get the latest code, upload it to the webserver, and unpack it over your existing copy of Gallery 2 (or use cvs instead to update the code). Keep your existing config.php in place, and don't touch your (g2data) data folder or the database.
  • 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.

How do I update my CVS version of G2 without losing my images?

See /gallery2/README.html for general instructions. Starting with alpha-4 upgrades are supported (you may not be able to upgrade from previous alphas however).. the basic process is to overwrite the codebase with the new code, then visit your gallery. You'll automatically see the upgrader if a core upgrade is required. If you don't see the upgrader then login as an administrator and visit Site Admin / Modules to see if any other modules need to be upgraded.

Development Specific

When will Gallery 2 to final?

We do not anticipate making any substantial changes between now and the final version. The purpose of release candidates is to let the product cool for a couple of weeks so that we can identify and fix any last minute issues that you may discover. The final is planned for fall 2005.

I really wish this feature were part of G2, is it planned?

It is possible that it is planned. See this list of requested features. Also see the feature request section on sourceforge . If you don't see your idea listed you can file a feature request on sourceforge and/or start a discussion about your idea in the G2 Development forum. If you do see your idea listed it may still be a long time before it gets implemented so if you or someone you know can help out with development, please do!

Something looks funny in IE6?

We recently removed a standards compliance patch for IE (caused more problems than it solved) and may not have resolved all rendering issues in IE. You should be able to figure out if it is an IE6 issue by viewing your site in something like Mozilla Firefox. If it works in Firefox but not IE6, its due to the code not yet being optimized for IE6.

I would love to write some modules, got anything useful for me?

Start with G2 Developer Starter Kit . There you will find reference to how our team works and where to find the needed documentation. First link there is the G2 Developers Guide which is a must-read before you start. Not every detail is described there yet and some stuff is outdated, but there you will get the general "feeling" on how and why our architecture is how it is. The API for all classes is self-documented with phpdoc in the code, which is extracted to the G2 API Documentation (last link in the Starter Kit). If you are on Windows and have trouble with the Makefiles to generate stuff for you, have a look at virshu 's howto Building Gallery 2 on Windows.

How can I integrate G2 into my website?

For basic integration see templates/global.tpl included with G2. Here you can add any html for your website header/sidebar/footer, etc. To include php code in this file wrap the code in {php} and {/php} tags (see http://smarty.php.net ). For application level integration (embedded G2) see the Embedding & Integration topic in the G2 Development forum and docs/EMBEDDING included with G2.

I have some experience in linux compiling and noticed some make files and other things that would appear to need compiling... do I need to?

The Makefiles are only needed by gallery2 module developers. If you are just using G2, you don't need to "make" anything. For developers, the Makefiles automate boring tasks such as:

1) generate compiled translation files (.mo) from source language files (.po), 
2) generate database schemas from entity definitions, 
3) generate interfaces to access members of entities. 

How can I "zap" my G2 data? How do I easily clear out /g2data and the DB?

You can visit the test tools page found at /gallery2/lib/tools/test/ and run the test titled "ResetGallery" or "ReInitializeGallery". You can read the description to see what each does, one is just a little more clearing than the other. If you have manually dropped your DB or some of the files are not deletable by you (for instance, they are owned by the webserver's user) you might find Bharat's Cleanup Script useful.

General Gallery2 FAQ

Does G2 work with Safe Mode PHP?

Gallery is NOT designed to work with safe mode. You can see the sticky thread in the G2 development forum for an in depth discussion. Also see this topic for details of some experiments in getting G2 to work with safe mode. To sum it up, they are going to get G2 working first. If it works in safe mode, or can be modified easily to work in safe mode... they may. If you are trying to disable safe mode in a .htaccess file make sure you use:

php_admin_flag safe_mode off 

and NOT:

php_admin_value safe_mode off

Why can't I upload big files (over a megabyte or two)?

Craig Goranson wrote a very informative email about how to fix this issue.

Gallery tries to override the upload_max_filesize and post_max_size directives in its .htaccess file. This means that changing the setting globally may still result in it being overridden at the .htaccess level, so you may want to just change the directive there instead of globally. Gallery tries to set both of the directives to about 20 megabytes, so this will only affect you if you're going to upload files over that size.

If you're using Apache 2, especially with something like RedHat, you may need to edit another directive, LimitRequestBody, as described in this forum post. Setting this directive to 0 (i.e. LimitRequestBody 0) will allow you to upload as big a file as you want (until you hit upload_max_filesize and/or post_max_size -- see the above email link for more information).

Does gallery remote work with G2?

It would appear it does, point gallery remote at the base url of your gallery. For instance, I would point it to "http://my.gallery.domain/gallery2/"

Can I update from G1 -> G2?

First things first. You should not plan on G2 replacing your G1 just yet. There are a few reasons, keep reading the FAQ if you want to know why. That said, G2 includes migration tools that will import all your G1 images to G2. This means G2 should be installed SEPERATLY from G1. On my server, G2 is installed in /gallery2 and G1 is in /gallery.

Where can I find NetPBM, jhead or ImageMagick binaries to use with G2?

You can find links to NetPBM and jhead on the Gallery Download Page. You might also find Image Magick binaries here

Where can I find unzip / zip binaries to use with the zip cart module?

You can find them here , but keep in mind this is a 3rd party site not under Gallery's control.

I customized a *.tpl file, but then removed it... but the customization is still showing up. Did I do something wrong?

If you remove a local/*.tpl or *.tpl.local file it won't switch back to the *.tpl file due to smarty caching. You can get it to switch back to *.tpl by clearing the smarty cache manually on the filesystem, using FlushTemplates test found in the /lib/tools/test/ page or by doing 'touch filename.tpl' which causes the last change time to update.

How can I move my gallery installation from one folder to another?

Here's a step by step guide:

  1. Deactivate and uninstall the url rewrite module if it's activate.
  2. Move the gallery folder (move/rename it with an ftp application, a file browser or with a shell). If you choose to move gallery from a subdirectory to the root of your website, just move all files and directories that are in the gallery folder to the web root directory.
  3. Edit config.php manually. If the g2data was within the gallery directory and you moved it, update the line:
$gallery->setConfig('data.gallery.base', 'some/path'); 

If you use a multisite install, you also have to update:

$gallery->setConfig('galleryBaseUrl', );

Save config.php, and you're done.

How can I move my gallery installation from one server to another?

Here's a step by step guide:

  • 0. Backup your installation!
  • 1. Upgrade G2 on the old server to the same G2 version which you plan to install on the new server.
  • 2. Deactivate the url rewrite module if it is active.
  • 3. Backup G2 on your old host = backup the database and the g2data folder.
  • 4. Copy the g2data folder and import the mysql database to your new host.
  • 5. If you're moving from a windows based server to a *nix (unix, linux, ...) based server, you will have to change each database table name from lower case (e.g. g2_albumitem) to a case-sensitive name (in this example g2_AlbumItem).
  • 6. Install the gallery2 codebase (extract gallery2.tar.gz/zip) on the new host. It should be the same G2 version as you last used on the old host (that's why you did the upgrade in step 1.).
  • 7. Have your webhosting partner change the owner of the g2data dir recursively to the webserver user, unless php cgi + suexec is used. If you don't understand this instruction, forward it directly to your webhosting partner. The webhost has to do this only once, I'm sure they will do it.
  • 8. I guess I wouldn't copy the config.php from the old host to the new host. Just run the installer, i.e. browse to newhost/gallery/install/. Make sure you choose "reuse existing database tables" in the database step. Point the installer in the appropriate step to the g2data folder (which is now not empty). And finish the installer.

If you choose to copy the config.php instead of running the installer (I'd really just run the installer, but if you insist...), you have to manually change: - the g2data path, - galleryId (at the bottom of config.php), - db name/user if needed

  • 9. Go to G2 Site Admin and change all paths if needed. imagemagick, zip, netpbm, ... all modules that depend on external programs have to be tested and reconfigured. Make also sure that the mail function of G2 works on the new host.

Why does the random image or random highlight not obey permissions? How come some of my images in private albums are shown?

Permissions are handled on an item by item bases, not an album by album basis. Just because "album01" is private, doesn't mean that "album01/album02/image3" is also private. This is by design and intentional, BUT the problem is in the interface which does not mention or explain this in any way. You can find the bug report here if you would like a better / different description.

I use NFS and Gallery isn't working, is there a solution?

By default Gallery 2 uses flock for locking and this is known not to work over NFS. Go to Site Admin / General and switch to database locking instead.

Is it my imagination, or is G2 slower than G1?

You're probably not imagining it. There are three main areas where Gallery 2 is going to be slower. Gallery 2 uses a database for its storage. This means that even the most trivial operations require communication with the database to get ansers. In comparison, Gallery 1 stores everything in fairly small flat files and it loads all the data into memory and then operates on it. For small Gallery installations on hardware that is 3+ years old, you're going to find that Gallery 1 runs a fair bit faster. However, Gallery 1 will not scale as effectively so as you start to get up to having 5-10K photos, you'll find that Gallery 2 is much more efficient. Having a database also allows other applications to interact with Gallery data, which is a big advantage over Gallery 1's proprietary data format.

Gallery 2 provides complete image security. If you restrict a photo based on its permissions, no outsider can get to it. This is in contrast to Gallery 1 that merely creates urls to images that an outsider could browse to, if he or she knew the url. However, this security comes at a performance cost. We are considering different approaches, including the possibility of allowing you to lower or remove this security threshold to increase your performance.

G2 is a much larger framework than G1. It's designed to be incredibly flexible and maintainable. This leads to having a lot more code and because of the nature of PHP, this causes pages to load a little slower. However, this also means that PHP accelerators like ionCube PHPA, Turcke MMCache, eaccelerator and Pear::APC, and Zend Accelerator (commercial) can effect very substantial performance increases when properly used in conjunction with G2. We recommend this option, if it's available to you (i.e. if you have full control over the php installation on your server).

Performance is an important factor to us. We have introduced caches at strategic places and are working on ways to improve all of the issues above to increase performance. It is secondary to making a fully featured product for now, but as we get closer to the official release date it will gain higher priority for the development team.

When I upload an image, G2 doesn't seem to create sized images or thumbnails... also, when I enter an album for the first time it takes a LONG time to load. What is the deal, yo?

G2 has some fundamental differences from G1. In G1, thumbs and sized images were created at image upload. In G2, these items are not created UNTIL they are accessed/needed. This means that the first time you view a sized image or album, it may take a while for the images to be generated. Of course, subsequent visits should be much faster because they already exist. I believe there are also plans for the ability to generate the needed images at upload or when ever the user wishes, independant of viewing them for the first time. Update: There is now a check box present during import and upload that allows for the generation of thumbs/sized images right then. Using this will increase the time it takes to upload/migrate, but will take care of it immediately instead of when a user first requests the image.

I am having trouble configuring a graphics toolkit (ImageMagick, NetPBM or ffmpeg). Help?

First- when the configuration asks for the path it is not asking for the path to the gallery2 module (like gallery2/modules/imagemagick). These directories are G2's interfaces to these programs and not the programs themselves. You need to find or install the binaries on your system, make sure they are executable, and enter the appropriate path in the configuration.

Can I rename main.php?

To use a different main php file after G2 is installed follow these steps:

  • Copy or symlink main.php to the new filename.
  • Add a line like this in config.php before the ?> at the end:
define('GALLERY_MAIN_PHP', 'filename.php'); 

Can I install if my server only allows .php4 extension for php files?

If your system does not accept ".php" as an extension for PHP files and requires ".php4" then rename install/index.php to install/index.php4 and proceed with the install. After installation follow the steps above to change main.php to main.php4. Note that upgrading is not yet supported with .php4 extension, so post in the forums if you have a setup like this so we get this completed!

Troubleshooting Gallery

I have a problem with something, what should I do?

To start with, updating to the latest code is a good idea. It is possible that it is already fixed. Next you should probably look around the forums to see if the problem has already been posted. Try your luck with the search function in the forums. If that doesn't help, you probably want to ask for help in the support forum. Include as much information as possible in your support request.

What information is required when I ask for help in the forums?

When you create a new topic in the support forum, please include the following information:

  • G2/system information: Copy'n'paste your G2 system information from "Site Admin -> Maintenance -> System information" (you have to click "run now" to get the system information).
  • Please add a link to your G2 install in the topic.
  • A phpinfo link is also very often needed. To create a phpinfo page on your server, do the following:
1. On your desktop, create a new text file
2. Open the text file and copy'n'paste the following:
 <?php phpinfo(); ?>
3. Save the text file and rename it to phpinfo.php (or any other file with the extension .php)
4. Upload the file to your gallery2 directory on the server
  • A description of the problem (and the steps to reproduce if it may be a bug)
  • The relevant error message and debug output.
  • For problems in the installer the debug output should be displayed.. post the error message at the top and look for the error near the bottom of the debug output.
  • For errors while using G2 you'll need to turn on buffered debug output in config.php and then look near the bottom of the output for your error message. If you're unsure where the error message is you may post a link to the entire debug output, but please don't post the entire thing.

Getting the error message from debug output is particularly important for ERROR_STORAGE_FAILURE errors, as this is the only way to get the detailed error message from the database.

  • You can activate G2's debug mode in config.php (instructions are in config.php, you have to change the $gallery->setDebug(false); line).

The more information you provide, the more likely we can help you and the faster the issue can be resolved.

I changed the language but nothing happens, what's wrong?

G2 depends on the system it runs on to switch to other languages than English. G2 needs php with gettext support and each language you want to switch to in G2 needs to be installed on your system. If you have command line access (ssh / telnet) to the (unix, linux) server, you can query for supported languages by `locale -a`. If only "C/POSIX" is returned, no other languages are supported and you need to reconfigure the locales and then restart apache. When configuring locales on your system, choose languages in ISO format, e.g. de_DE and not languages in UTF8 format, e.g. de_DE.utf8.

Why can't I install with MySQL 4.1 or higher?

If the installer gives you an error like "Client does not support authentication protocol" then the MySQL support builtin to your PHP is using an older password scheme than your MySQL database. See here for more information and a workaround to get you up and running without having to recompile or upgrade your PHP.

I get an error about "max key length" installing with MySQL?

If you see this error while installing the Core module:

Specified key was too long; max key length is 1000 bytes 

then you need to switch the database character set to something other than utf8. Currently some indexes we use exceed this default MySQL limit if the charset is utf8.

I seem to be running into some sort of MySQL query limit, is there anything that can be done?

Some hosts setup a query limit on your MySQL database. This is usually a per hour limit and would be restored in time. Floridave believes that a reasonable value for this would be 50-70k, but some hosts might set it as low as 10k. See if your host will bump it up a little bit perhaps.

I get only a blank screen when trying to view my Gallery, what's wrong?

This can have various reasons. The first thing you should check is your PHP memory limit and other PHP configuration parameters. In most cases, G2 requires a memory limit of at least 16 MB, if you are using GD, it may require even a higher limit.

When I click on item thumbnails, nothing happens, what's wrong?

Probably your PHP memory limit is too low. Increase your PHP memory limit to at least 16 MB. If the problem persists, you should activate immedate debug mode in config.php and report the problem in the forums.

Why do I see stray NetPBM and cmd.exe processes that never go away on my windows server?

If NetPBM is given a file that it can't support, it may try to put up a dialog box telling you about the error before continuing. Since your server can't display those error boxes, the rest of the image processing operations wait for you to click an "OK" button that you can't see. This may also result in G2 hanging for 30 seconds since it is waiting for the image processing to complete also. ImageMagick does not appear to have this problem.

What about the warning for missing & modified files in the installer & upgrader?

If there is a warning for missing or modified files in the installer or upgrader, you should take it seriously. Neither the install or upgrade process nor G2 as an application can work correctly with missing or modified files. Upload the modified / missing files again to your server until the warnings disappear. Possible reasons for missing / modified files:

  • Error during the FTP upload of the Gallery 2 files
  • Use of Winzip or other problematic archive programs to unarchive the Gallery 2 .zip.
  • There are reported issues for several unarchive programs on OSX

If you are a cvs user, a warning for missing or modified files in the installer / upgrader systemcheck step is the norm. But if you experience any problems, this is surely one of the first places you should look into.

I get lots of "Warning: exec(): Unable to fork [cmd /c ...]" at the module's step in the installer for G2 (on the ImageMagick module) under Windows/IIS. Now what?

You need to give permissions for IIS to be able to read and execute the command interpreter ("cmd.exe"). Without it, Gallery won't be able to call external executables (like ImageMagick). Required steps:

1. Open a cmd-prompt with "Start", "Execute", then type "cmd.exe". Hit ENTER. 
2. At the prompt, type: 

This adds the "read" permission to the IIS-user for the cmd.exe. Close the prompt and then try activating the imagemagick module again.

I use apache's mod_layout and notice some odd error messages, what is the problem?

If you use mod_layout with Apache, make sure it is disabled for gallery files. Gallery sometimes sends binary data back from a php file, so adding a header or footer to these requests will corrupt the data! Adding the following lines to your apache config file or your .htaccess should fix it.

# Disable layout header and footer for Gallery2 
LayoutIgnoreHeaderURI /path/to/gallery2/*.* 
LayoutIgnoreFooterURI /path/to/gallery2/*.* 
# PHP Gallery2 overide Layout 
<Directory /path/to/gallery2/> 

How to set/use Gallery in debug mode?

Edit your config.php and turn on buffered debug mode like this:


Then try again. This time, you'll get quite a lot of debug output when you get the error. Look towards the bottom of the debug output and scan backwards for anything that looks like an error, then report that in the support forums. Usually that will give us enough information to work with. If you can't understand what you're seeing, err on the side of posting more info. If it's going to be more than 30-40 lines of output, you should save it into a text file and publish it on your own website and post a link to it here (so that the forum remains readable).

Where I should see dates I see "Wrong charset, cannot convert" or "Illegal character encoding" or "Illegal recode request".. what is wrong?

Some operating systems report invalid character sets to PHP leading to errors when trying to convert system-generated content (like day/month names in dates) to UTF-8. Work around this problem by placing the following in config.php:

require_once(dirname(__FILE__) . '/modules/core/classes/GalleryCapabilities.class'); 
GalleryCapabilities::set('systemCharset', 'ISO-8859-1'); 

Replace 'ISO-8859-1' with the appropriate character set for your system.

I can't install G2, what should I do?

So you tried to install G2 but you get an error, probably in the install core module step. See the list of frequent installation errors.

I get a blank page / a network/webserver error, what's wrong?

If you are using PHP 5.0.3 or earlier PHP 5 versions, this is probably because of a bug. Therefore, these PHP 5 versions are not supported by G2. Either change to PHP 4.1+ or to PHP 5.0.4+.

This bug should occur in advanced search, in the publishxp module and in other places of G2.

I can't login anymore, what can I do now?

  • If you see an error message that the login information is wrong, then you used the wrong username/password to login. If you forgot your login information, use the forgot password link.
  • If you've upgraded from a version older than beta 4, please read the README.html. By clearing the cookie cache of your browser, it should be fixed.
  • If you just have changed the cookie path / domain settings in the site admin options, first delete the GALLERYSID cookie in your browser. If that doesn't fix it, or if you can login again but it shows the GALLERYSID parameter in all URLs even if you browse around in G2, you most probably entered wrong values for the cookie path/domain. If you can't login anymore, deactivate cookies in your browser and login in G2. Go to site admin and fix the cookie path/domain values.
  • If you're using a version older than RC-1 and G2 is running on a IIS webserver older than IIS-6, upgrade to G2 to RC-1 or later. We had to fix an IIS-5 bug because MS was unable to fix it in the webserver.

I get a lot of "Notice: Only variable references should be returned by reference in "... notices, what's wrong?

You're probably running a PHP 4.4.0+ or a PHP 5 version. If not, please create a new forum topic and report your issue.

We have addressed these notices in G2 beta 4. If you're running an earlier version, the notices should go away with beta 4 or later. Please upgrade.

If you're running G2 beta 4 or later and still get these warnings, chances are good that PHP bug 34009 applies to your setup. You can only get rid of the notices by adding

error_reporting(error_reporting() & ~E_NOTICE);

right after the <?php line of your bootstrap.inc.