Gallery2:How do I Install Gallery2 - Gallery Codex
Personal tools

Gallery2:How do I Install Gallery2

From Gallery Codex

Installing Gallery 2

Instructions in other languages:

Instructions for specific setups / platforms:

Prerequisites

Before you can install Gallery 2, you need an up and running webserver with PHP support and a database server. For a full list of all requirements, please read our Installation Requirements page.

Webhosting Users

If you install Gallery 2 on a hosted webserver like most users do, you don't have to worry about how to install and set up a webserver etc. since it's all done and prepared for you. Your webhost has probably a control panel or other administration tools where you can create an empty database. Just skip this section and continue with Preparing to install.

Note: Some webhosts offer a 1-click installation of Gallery 2 saving you the trouble with installation preparation where you can install Gallery through the administrative panel of your website. We know about the following auto-installers:

Below are links to blogs and web sites that have installation instructions for Gallery on a typical shared hosting web space:

Setting Up Your Own Webserver

Setting up your own webserver is not the easiest thing to do. There are some free packages available that install a complete webserver with PHP and a MySQL server for you with a few clicks, but if you run into problems, you'll soon see that it's not very intuitive if you have no experience in such things.

You can follow this step by step guide to setting up an Apple Mac as a webserver

Internet Connection

If you don't have a static IP address or a dynamic DNS (dnydns) account, your Gallery 2 on your own webserver will only be accessible to you and other computers on your local network and none of friends or customers can view your Gallery in the internet. We assume that you either have a static IP address / dyndns account or that you want to access Gallery 2 only from your intranet / desktop computer.

Easy To Install All-In-One Packages

If you don't have installed any of the required components yet and if you prefer to not get involved with the technical details, there are some easy to install, all-in-one packages that install apache + MySQL + PHP with a few clicks.

Operating System

If you want to install Gallery 2 on your own computer / server, then we recommend linux / *BSD as operating system since these are our primary development platforms and these are also the platforms most professional webhosting companies use. Other operating systems are also supported of course. There are various Linux distributions. Debian and Gentoo (among others) are highly recommended because they are mature, stable and well-suited for server applications and they include excellent package managers which resolve dependencies for you. Installing a webserver, php or a database server on such linux distributions is as easy as entering a single command à la "emerge apache2" or "apt-get install apache".

Webserver

Apache2 is the webserver of our choice. Some Gallery 2 features like short URLs are only available for apache (short URLs are also available for other webservers since Gallery 2.1).

Database

Gallery 2 is mainly developed for MySQL, but it runs also very well with PostgreSQL and DB2. Gallery 2 is not very well tested with Oracle. You can expect the best performance with MySQL, also because we use built-in functions of MySQL that we have to mimic in other database servers with user-defined functions.

PHP

You can get precompiled PHP binaries or the whole sourcecode from php.net. If you compile it on your own, don't forget to compile database support into PHP (e.g. --with-mysql= ... and --with-mysql-sock=... if you're using MySQL). Also, for translation / multilanguage support, you'll need gettext. And there are a lot more PHP compile options / extensions that are either required (e.g. PCRE) by Gallery 2 or useful in general. If you rely on GD (an image toolkit that is built-in into PHP) instead of the external, mostly superior image toolkit binaries (imagemagick, netpbm, graphicsmagick), then you shouldn't forget to add all the image formats to the PHP compile options (--with-jpeg=... , --with-png=..., etc). Compiling PHP is a topic of its own. Gentoo, Debian, ... will configure and compile it for you with a single command. And you can find numerous tutorials and HOWTOs about this topic as well as about the whole webserver + mysql + PHP topic in general.

Preparing to install

1. Latest Version - There are four ways to get the code.

  • Tarball - You can download a prepackaged file as a tarball or a zip file from SourceForge.
  • Pre-Installer - If you only have FTP access to your webserver and don't have the option to extract zip or tar files directly on the server, you should give the Gallery 2 Pre-Installer a try. It transfers the archive directly to your webserver and extracts it for you.
  • Nightly Snapshot - You can download a tarball or zip file with a snapshot of the most recent code. Find links to these on the Gallery Download Page.
  • Subversion - This is a better way to get the latest code, but it’s for advanced users. Follow the Subversion instructions to obtain the latest Gallery 2 code. It’s easier to stay up to date with this method since you can run one command and get the latest code at any time.

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. The general practice for doing this involves making the files or directories writeable by your system user as well as the web-server's group. For instance:

$ cd $HOME
$ mkdir g2data
$ chgrp apache g2data
$ chmod 770 g2data

This may require 'root' privileges on a Linux/Unix system which is why you may need to contact your administrator in order to do this. It is, however, much more secure, particularly on a shared system.

3. Database - Right now we support MySQL, PostgreSQL, DB2, Oracle and MS SQL Server. 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.

MySQL Instructions

$ mysqladmin -uroot create gallery2
$ mysql gallery2 -uroot -e"GRANT ALL ON gallery2.* TO username@localhost IDENTIFIED BY 'password'"
  • Choose your own username and password
  • If MySQL denies you access, try adding "-p" right after "-uroot" in each command

PostgreSQL Instructions

Frstly create a user (gallery2 for example) to connect to the database:

$ createuser -l -P gallery2
Enter password for new role:
Enter it again:
Shall the new role be a superuser? (y/n) n
Shall the new role be allowed to create databases? (y/n) n
Shall the new role be allowed to create more new roles? (y/n) n

Then create a database owned by this user:

$ createdb gallery2 -E UNICODE -O gallery2

If it complains that UNICODE is not a valid encoding name, then try:

$ createdb gallery2 -E SQL_ASCII -O gallery2

If it complains about that, too then try:

$ createdb gallery2 -O gallery2

On Windows 2003 Server (and maybe on other versions too) you have to write the database name at the end of the command:

C:\> createdb -O gallery2 -E UNICODE gallery2

Don't forget to allow gallery2 to access the database modifying your pg_hba.conf. For instance you can add the following insecure line:

hostnossl gallery2   gallery2      127.0.0.1/32          md5

Now you should be able to use user gallery2 to connect your gallery2 database.

Oracle Instructions

$ create database gallery2 {additional parameters};

DB2 Instructions

See http://codex.galleryproject.org/index.php/Gallery2:DB2

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.

Installing Gallery 2

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:

  • Fastest way: Upload the gallery package to your web server archive via FTP or another method, then unpack it using an interactive shell session (eg. ssh or telnet). Example unpacking commands (choose the appropriate one):

For .tar.gz archives

$ tar xzf gallery2.tar.gz

For zip archives

$ unzip gallery2.zip

If you do not have shell access, you can ask your provider to do it for you, or you can make a miniature PHP script containing one of the above commands like this:

PHP code for opening .tar.gz archive

<?
$output = shell_exec('tar xzf gallery-2.0.2-full.tar.gz');
?>

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.

  • Easiest (but slowest) way: If you don't have shell access, you can upload the complete contents of the Gallery 2 archive to the webserver with an FTP program. This may take a lot of time and be 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. Consider using a smart FTP program like FileZilla to make sure that your transfer goes smoothly.
  • Advanced way: Subversion

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

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

4. System Checks - The installer checks your system to make sure that it will support Gallery 2. Make sure that all checks are successful! __MAGIC_REMOVE__12914__

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

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

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

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

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

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

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

12. Check Security - Gallery 2 walks you through the process of locking down your new config.php. __MAGIC_REMOVE__12959__

13. Finished! - Congratulations! You have successfully installed Gallery 2! __MAGIC_REMOVE__12965__

Get Notified About Updates

It is highly recommended to subscribe to the announcements mailing list to get notified about Gallery updates. We keep this mailing list very low volume to ensure that you only get notified about important announcements like security patch releases.

Installing Modules (Plugins) with External Dependencies

Gallery 2 has also modules that depend on external binaries. These modules won't work if the binaries they depend upon are not installed on the webserver. Under this category of modules fall the imagemagick and the netpbm module which are responsible for generating small preview images (so called thumbnails) and resized versions of your images.

If Gallery 2 failed to install and activate modules like imagemagick, netpbm, or zipcart, then it failed to automatically detect the presence and location of the required external binaries. Most probably, this means that your server doesn't provide the necessary binaries to use these Gallery 2 modules. Even if the Gallery 2 install did detect and activate the module, it may still not work. This because the install and activation is not checking thoroughly for the version of the binary program. Gallery 2 may need options or bug fixes not present in an older version found. Use the test button in the plugin's configuration area to see if maybe a check there detects the minimum version needed.

See Installing Modules With External Dependencies for further information.