.DOC.doc

Content

I

System setupsInstallation Instructions

LAMP Server

Gallery

Database

Image Processing Library

Optional Items

Installing Gallery 2

Prerequisites

Webhosting Users

Setting Up Your Own Webserver

Internet Connection

Easy To Install All-In-One Packages

Operating System

Webserver

Database

PHP

Preparing to install

Unix Example

Windows Example

MySQL Instructions

PostgreSQL Instructions

Oracle Instructions

DB2 Instructions

Installing Gallery 2

Installing Modules with External Dependencies

Install Google Earth

II

MBM PagesIndex Page

Description

Use Cases

Functions

User Level

Users Page

Description

Use Cases

Functions

User Level

Species Page

Description

Use Cases

Functions

Users

Media Page

Description

Use Cases

Functions

Users

Expert Page

Description

Use Cases

Functions

Users

Admin Page

Description

Use Cases

Functions

Users

Notes

Permissions Table

Group Descriptions

Everybody

Users

Expert

Admin

----------------------------------------------------------------

Installation Instructions

Step 1: LAMP Server

The MBM Team recomends running Gallery/MBM on a Linux server with Apache, MySQL and PHP. For a quick and simple set up you can use Ubuntu Server. Simply choose the LAMP option on install and you will have a fully functional server ready for Gallery/MBM in less than an hour. For full Gallery functionality some additional PHP Modules are required. A more detailed description of all the Gallery requriements, as well as information on how to install them, can be found on Gallery's site:

Step 2: Gallery

Installation Requirements

Gallery has certain technical requirements that must be met (i.e. installed and/or configured) on your server before you attempt to install it.

Web Server

Apache

Apache (Apache 1, Apache 2) is the most popular web server in the world, and is the one recommended by the Gallery Team for use with Gallery 2. It can be downloaded from the Apache HTTPD Project's site

IIS

Microsoft's IIS (Internet Information Services) web server has also been known to work. But there are some limitations. See Known Issues for details. Short URLs work, but G1 redirects are not yet supported for IIS. Also take a look at our Windows Server 2003 and IIS 6 Howto.

PHP

Gallery is written in PHP (recursive acronym for PHP: Hypertext Preprocessor). It is one of the most popular, free web-based languages in the world today. It can also be downloaded gratis from the PHP Project's site.

PHP Version Compatibility

Gallery requires at least version 4.x (4.1.0 or more recent; Gallery 2.2 requires 4.3.0 or more recent) or 5.x (5.0.4 or more recent) to function properly. Note: Gallery 2 has problems with PHP 5.0.5 due to a bug in PHP .

PHP 5 is highly recommended - PHP will not release any security updates for PHP 4 after 2008/08/08. If your webhost is still running PHP 4, please ask them to switch to PHP 5 as soon as possible for security reasons (not just for Gallery, but for all PHP applications).

Gallery 2.4 will require PHP 5.2 or later.

PHP 6 is incompatible with Gallery 2.0 - 2.3. Gallery 2.4 (first release in 2008) is planned to be compatible with PHP 6 though.

PHP Settings

In addition to a basic PHP installation, Gallery requires certain PHP settings to be setup correctly in order to function optimally.

safe_mode safe_mode must be disabled in order for Gallery to work correctly disable_functions The disable_functions directive must not include the function

set_time_limit. file_uploads file_uploads must be set to On if Gallery is to be able to upload files

from your computer upload_max_filesize and post_max_size These configuration parameters control

the maximum file size that can be uploaded. Adjust these from the default 2M setting to something larger if you have problems uploading pictures from higher resolution cameras.

If you want to use the localization feature then PHP should be configured with the gettext option enabled.

alindeman has created a script to check your Gallery for potential problems due to PHP settings. Download the script and upload it to your host. Open the script in your browser (http://www.example.com/gallery/ghcc.php). If any tests fail, you may need to adjust your settings before trying to install Gallery.

Database

Gallery 2 requires one of the following database management systems (DBMS): MySQL 3.x or 4.x, 5.x, PostgreSQL 7.x, 8.x, Oracle 9i or 10g, IBM DB2 8.2, Microsoft SQL Server

Image Processing Library

Gallery 2 requires either NetPBM 9.x or newer, ImageMagick 4.x or newer, GD 2.x or newer, or GraphicsMagick 1.x or newer in order to operate (e.g. generate thumbnails) on your images and photographs.

More information on how to install an image processing library is explained on Installing an Image Processing Library

Optional Items

mod_rewrite

mod_rewrite is an Apache server extension that enables your Gallery 2 to use "short URLs." That is, instead of

http://www.example.com/gallery/main.php?g2_view=core.ShowItem&g2_itemId=17&g2_serialId=2

the URL would be reduced to

http://www.example.com/gallery/v/albumName

Gallery 2 will attempt to automatically check for the presence of mod_rewrite during the installation process if you select the URL rewrite module.

ffmpeg

If the Ffmpeg module is activated, it will automatically create thumbnails for movies. The ffmpeg module requires the ffmpeg binary. If you have shell access to the server, you can install ffmpeg with the packaging system of your linux distribution.

Dreamhost directions (should be similar to most hosts.

dcraw

Dcraw is a graphics toolkit that can be used to process RAW images produced by high end digital cameras. You must install the dcraw binary to activate the dcraw module in G2.

jhead

jhead is a free tool that can be used to extract EXIF data from images, which most digital cameras now add to photos. If enabled, EXIF data will be preserved when operating with the netpbm toolkit on your original photos in G2. You don't need jhead for the EXIF features in G2, a library written in PHP is used to extract the EXIF data from images. Imagemagick and GD don't need jhead to preserve the exif data when manipulating images.

infozip

infozip is a free tool that allows Gallery to unzip ZIP archives so that you can easily upload multiple photos. If enabled, you will be able to upload a ZIP archive as you would any other single picture, and Gallery will add all the images in the archive.

zip / unzip

zip is required for the zip download module and unzip for the archive upload module. Most linux / unix based platforms already have these binaries. For MS Windows, the zip.exe / unzip.exe binaries from cygwin are also an alternative, make sure you select the zip tool under archive during the install (it will not install by default), it is located in /bin/.

Installing Gallery 2

Instructions for specific setups / platforms:

Installation on Mac OS X

Installation on Windows with IIS and FastCGI

Installation on Debian

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.

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.

XAMPP - http://www.apachefriends.org/ (for Windows, Linux, and other operating systems)

MAMP - http://www.mamp.info/ (for Mac OS X) WAMP - http://www.wampserver.com (for Windows)

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.

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

$ 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

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 -E UNICODE gallery2

Oracle Instructions

$ create database gallery2 {additional parameters};

DB2 Instructions

See http://codex.gallery2.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.

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!

Installing Modules 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. Install Google EarthMake sure you first download Google Earth. Once the download process has been completed, you should automatically be able to open the software and begin using Google Earth.If you experience issues installing Google Earth through the Google Updater, you can download the latest version of Google Earth directly from the following links:Google Earth for PC

Google Earth for Mac

If you automatically launch Google Earth, an existing account may have been installed on that machine. Select the option Run Free Version in order to use the application.

MassBio: MBM Pages

Index Page

Description Front page for the MBM site. Will be the first page seen by vistors and any users who have not yet signed in.

Use Cases

User first time logs in the MBM system Second Grade Teacher Using MBM Site Pictures Search Spider Expert Using MBM Site Access Personal Page

Functions

Sign in Register Search Recent Media Thumbnails Site information

User Level

Everybody

Users Page

Description Default page for all members who have already signed into the MBM site.

Use Cases

Second Grade Teacher Using MBM Site Pictures Search Spider Expert Using MBM Site Access Personal Page

Functions

Sign out Search Recent Media Thumbnails News

User Level

Users Experts Site Admin

Species Page

Description Page for each individual species containing that species media and basic information.

Use Cases

User submits a request for MBM uploading rights User uploads photos to the MBM web site Second Grade Teacher Using MBM Site Pictures Upload Second Grade Teacher Using MBM Site Add Comments

Functions

Sign out Search Species media thumbnails Upload media Post comment Taxon breadcrumbs

Users

Everybody Users Experts Site Admin

Media Page

Description Page for full and alternate versions of media.

Use Cases

Second Grade Teacher Using MBM Site Add Comments

Functions

Sign Out Search Post Comment

Users

Everybody Users Experts

Site Admin

Expert Page

Description Page for Experts to manage their media and accounts

Use Cases

Spider Expert Using MBM Site Tag Media Spider Expert Using MBM Site Access Personal Page Spider Expert Using MBM Site Configure Personal Page

Functions

Users

Experts Site Admin

Admin Page

Description Page for preforming admistrative functions.

Use Cases

Administrator updates recently uploaded data Administrator approves requests for higher access rights Administrator approves user's request for uploading rights

Functions

Species XML Loader User permissions New media, comments and ratings

Users

Site Admin

Notes

Permissions Table

core comments rating

Everybody view view view

Users add view view

Experts edit/del edit/del add

Site Admin all access all access all access

Group Descriptions

Everybody is the default options for all users and guests. This is the highest permissions level for anyone not signed into the site.

Core System - View all versions of media. No access to add, edit or delete media. Comment System - View all comments. No access to add, edit or delete comments. Rating System - View all ratings. No access to add, edit or delete ratings.

Users is the default group for all members that have signed into the site.

Core System - View all versions of media. No access to add, edit or delete media. Comment System - View all comments. Add, edit and delete comments posted by the user. Rating System - View all ratings. No access to add, edit or delete ratings.

Expert is used by those members approved by mbm administrators to upload and manage media.

Core System - View, add, edit and delete media. Comment System - View, add, edit and delete comments. Rating System - View and post ratings.

Admin is the used by those who are administrators of the mbm web site.

Full Access - Access to all Gallery functions. Including media, comments, ratings, users, permissions and album structure.