**************************************************************
* Manual for setup.php, the PHPGallue installer and updater *
**************************************************************

PHPGallue is a server-oriented, PHP-based image management system
with a web frontend.

home page: http://gallue.sf.net
sourceforge.net project page: http://sourceforge.net/projects/gallue/
IRC channel: #gallue on irc.freenode.org

0. Quick install guide
======================

For those who don't read manuals: Some commands to install PHPGallue
in your home directory.

umask 0022 # create files world-readable
# by default
mkdir -p ~/pub/PHPGallue/ # create target directory
mkdir -p ~/public_html/PHPGallue/admin/ # create htdocs directories for
# PHPGallue.
mkdir -p ~/pub/cache/gallue/ # create cache directory
touch ~/pub/config.xml # create empty configuration file
chmod a+rw ~/pub/cache/gallue/ # make cache directory world-read-
# and-writeable
chmod a+rw ~/pub/config.xml # make config file world-read-
# and-writeable

Now unpack the PHPGallue tarball inside ~/pub/.

#If you want to install the svn version instead:
#
# svn co https://svn.sourceforge.net/svnroot/gallue/PHPGallue/trunk/ ~/pub/PHPGallue/

Now put soft links to the main PHPGallue scripts inside the htdocs directory:

ln -s /home/<user>/pub/PHPGallue/*/htdocs/* ~/public_html/PHPGallue/ # link regular scripts
ln -s /home/<user>/pub/PHPGallue/*/admin/* ~/public_html/PHPGallue/admin/ # link admin scripts

If everything worked as expected, you can run the setup script at

http://localhost/~<user>/PHPGallue/admin/setup.php

with your browser.

To update the table definitions and the config file after updating the PHPGallue
libraries just run the setup script again. It will automatically find and update
the existing installation.

1. Preparations
===============

1.0 Required Software
--------------------

In order to run PHPGallue, you need the following software on your computer:

- UNIX-like operating system (tested on Linux and OS X) with at least shell access
- Web server (tested with Apache 2.0 and Apache 1.3.x)
- PHP 5 (CLI and Apache module - works with CGI and fastcgi, too, but most
users prefer to run PHP 5 as an Apache module)
- PHP 5 extensions: mysql, mbstring, exif
- Perl (tested with Perl 5.8.x)
- ImageMagick
- MySQL server version 4.1 or newer
- UNIX utilities: file, GNU tar, GNU find

1.0.1 PHP configuration

On a default PHP installation uploading an image fails sometimes without
an error message. This is not really a bug, but a PHP feature:
By default the maximum size of file uploads is set to 2 MB in the PHP
configuration file php.ini. For an image gallery this is usually not enough.

In order to allow bigger uplods, you have to increase the max. overall size
of POST data, too. If you want to handle large amounts of images, it can be
useful to slightly raise the memory limit.

These settings will work for most people:

memory_limit = 16M
post_max_size = 100M
upload_max_filesize = 100M

1.0.2 Apache configuration

It is recommended to allow symlinks (option "SymLinksIfOwnerMatch")
for the PHPGallue htdocs directory.

1.1 Files and directories
------------------------

PHPGallue will need four locations on your system:

- Location of library files (world-readable)
- Configuration file (read- and writeable for PHP scripts, ideally not
world-readable)
file contains database password
- Cache directory (read- and writeable for PHP scripts, ideally not
world-readable)
contains cached image data
- htdocs directory (world-readable)
Location of the main PHP scripts which are invoked by the web server

The libraries can be placed wherever you want, as long as they are
world-readable. They should be placed outside the web server's document root,
e.g. somwhere below your home directory. For a system-wide installation
/usr/local/share/gallue/ is recommended.

The configuration file must stay somewhere outside the document root because it
contains sensitive information like the database password. Ideally it is only
read- and writeable by you and the PHPGallue scripts. The usual location
(system-wide installation) is /etc/gallue/config.xml. See also section 1.2!

The cache directory contains cached image data and temporary files. It must be
read- and writeable by the PHPGallue scripts. Usually you don't need access to
these files yourself. The usual location (system-wide installation) is
/var/cache/gallue/.

The looation of the htdocs directory strongly depends on your web server's
configuration. You may use yor personal web directory (~/public_html/) or a
system-wide directory, typically somewhere below /var/www/. If unsure, ask your
system administrator.

1.2 Security
------------

1.2.1 Other users on your computer

You should not run PHPGallue on systems where non-trustworthy people have user
accounts!

On most systems every user that can create PHP scripts that are executed by
the web server, e.g. in his private web directory "~/public_html/", can gain
unlimited access to the image management system.

This is a general problem of all PHP and CGI scripts, because they are
executed by the web server and therefore run under the web server's UID
(typically "www-data") and not under the file owner's UID. This means that
every PHP script on your computer can read and write the PHPGallue configuration
file.

PHPGallue won't work with PHP safe mode, but with Apache a safe setup is
possible by using the suexec wrapper and PHP as cgi or fastcgi handler instead
of mod_php5. This is not scope of this manual. Please contact your system
administrator!

1.2.2 Intruders from the net

If you run PHPGallue over a connection that is not secured with SSL, everybody
along the line can steal session cookies and sniff your password. PHPGallue
doesn't provide support for SSL explicitly, but it should be no problem to run
PHPGallue over a SSL connection. Running a server that supports SSL and normal
access in parallel will require a special setup. Please contact the authors of
this software for help in this case.

1.3 Download PHPGallue and prepare to run the installer
-------------------------------------------------------

The commands below will install PHPGallue inside your home directory. I assume
that your htdocs directory is /home/<user>/public_html/ and you want to install
the library files to /home/<user>/pub/PHPGallue/. The cache directory will be at
/home/<user>/pub/cache/gallue/ and the config file at
/home/<user>/pub/config.xml.

Please replace <user> with your UNIX login name in this manual.

Make sure the web server can read these files inside your home directory!

Change the paths in the commands below if you want to install
at different locations.

Now unpack the PHPGallue tarball inside ~/pub/.

# If you want to run the "cutting edge" development version from the Subversion
# repository instead of the official release (only
# recommended for developers and somewhat risk-loving folks), use these commands to check
# out the current version:
#
# svn co https://svn.sourceforge.net/svnroot/gallue/PHPGallue/trunk/ ~/pub/PHPGallue/

Now put soft links to the main PHPGallue scripts inside the htdocs directory:

ln -s /home/<user>/pub/PHPGallue/*/htdocs/* ~/public_html/PHPGallue/ # link regular scripts
ln -s /home/<user>/pub/PHPGallue/*/admin/* ~/public_html/PHPGallue/admin/ # link admin scripts

If you are running Apache, this will only work if the Apache configuration
option "SymLinksIfOwnerMatch" is activated. If not, the web server won't accept
symbolic links. In this case just replace "ln -s" with "cp -R" in the commands
above to copy the files instead of just linking them.

Most users protect the administrative scripts in ~/public_html/PHPGallue/admin/
against unauthorized access. This is not absolutely necessary, but recommended.
Please consult the Apache manual:

http://httpd.apache.org/docs/2.0/howto/htaccess.html

If everything worked as expected, you can run the setup script at

http://localhost/~<user>/PHPGallue/admin/setup.php

with your browser.

2. setup.php documentation
==========================

setup.php will try to guess most configuration options and skip values or steps
where it can guess reasonable defaults. To access a specific step, just
click it's link in the left menu. You'll enter "expert" mode and all fields are
displayed. A green background indicates that the field value is OK.

If a steps requires previous steps to be completed, it is shown as normal text
instead of link in the left menu.

2.1 Authentication
------------------

The installer has to make sure that you are allowed to run it. It asks you to
create a file inside the directory to prove that you have write access to this
directory. The key displayed is unique for every session. It cannot be used by
another visitor, so it is relatively safe to put it inside a public web
directory. Your session can still be compromised by sniffers along the line or
through an insecure server setup!

2.2 Configuration file
----------------------

Please enter the absolute path of the PHPGallue configuration file - in the
above example /home/<user>/pub/config.xml. The file must exist and be writeable
for setup.php. It might be an empty file or an existing configuration. Setup.php
will try to use the values from an existing configuration.

2.3 Locations of required files in the file system
--------------------------------------------------

In this step you enter the positions of required files for PHPGallue: The cache
directory, the PHPGallue library files and external programs.

Most probably setup.php will ask for the cache directory. This directory must be
read- and writeable for setup.php. If you followed the instructions above, this
is /home/<user>/pub/cache/gallue/.

If your web server doesn't accept symlinks and you had to use "cp -R" instead of
"ln -s" to put the necessary files inside the htdocs directory (see above),
you'll be asked for the path to the PHPGallue installation, too. In the above
example, this is /home/<user>/pub/PHPGallue/.

On a recent Linux system where all required software is installed through the
regular package manager, setup.php will be able to determine the paths of
external programs automatically and you won't have to enter the paths yourself.
On other UNIX system you'll have to enter the correct path in some cases.

2.4 Information for connecting the database server
--------------------------------------------------

It is recommended to use a separate database for PHPGallue, but you can create
the tables inside a database with other tables as long as the table names don't
conflict. You can even run separate installations of PHPGallue inside one
database by using different table prefixes.

By default setup.php won't overwrite existing tables. To change this behaviour
use the drop-down list at the bottom of the HTML form ("What to do with existing
tables").

To create a database named 'gallue' and an user named 'gallue' with password
'replaceMe' and all required privileges, you can use these SQL commands (as
database user 'root'):

CREATE DATABASE gallue;
GRANT SELECT, INSERT, UPDATE, DELETE, LOCK TABLES, CREATE, ALTER, INDEX,
DROP, CREATE TEMPORARY TABLES
ON gallue.* TO gallue@localhost IDENTIFIED BY 'replaceMe';

If your database root password is empty and setup.php can't update an existing
PHPGallue installation, setup.php will create a database and an user with random
password itself.

If you are running setup.php to update an existing configuration, it will try to
update the table structures automatically without deleting existing fields and
indexes.

2.5 Create administrator account
--------------------------------

If no user with administrator privileges exists, you'll be asked for a login
name and password. If you lose your admin password, you can create a new admin
account by clicking on the link "Create administrator account" in the left menu
to enter this step manually.

2.6 Create first user account
-----------------------------

Most users don't use PHPGallue as administrator for "normal business" because
this violates the privacy of other users and they could accidentally change
things that don't belong to them.

If no user with "author" privileges exists, you'll be asked for information to
create a new one. To add or manage additional users, log into the web interface
as administrator after setup is completed. To create a new user using the
regular web interface, chose "User" in the "New" menu on top of the page. To
manage existing users, chase "Users" in the left menu.

2.7 Create "locations.inc.php"
------------------------------

This file contains the path to the configuration file and the PHPGallue
libraries. It is included by all PHP scripts inside the htdocs directory so that
they use the right configuration. Just follow the instructions.

2.8 Enter the absolute URL of the PHPGallue script directory
------------------------------------------------------------

This step assumes that you've got a "normal" installation according to the
manual above. Just enter the URL of the PHPGallue directory inside the htdocs
directory. If you followed the instructions above, this is probably
"http://<your hostname>/~<user>/PHPGallue/". Replace <your hostname> and <user>
with values fitting your system.

2.9 Congratulations!
--------------------

You are done. :-)

(Hope so. Otherwise contact us:
http://sourceforge.net/projects/gallue/
IRC: irc.freenode.org #gallue
)

3. System-specific issues
=========================

3.1 OS X
--------

You need to install most of the required software yourself. Only Apache 1.3,
"file" and GNU tar is already installed. By default the personal web directory
is ~/Sites/ and an user's home directory is /Users/<user>/. For MySQL and PHP 5
there are native OS X packages on the web. You may install the other software
with fink or DarwinPorts. The default OS X "find" (BSD flavor) doesn't work with
PHPGallue, you need GNU find (DarwinPorts or fink package "findutils").

3.2 Linux
---------

All required software is available as native package as long as your
distribution is up-to-date.

4. Special setups
=================

PHPGallue is designed to run on clusters, but we think most users will be happy
with a "default" installation on a single stand-alone cluster node, therefore
setup.php doesn't provide means for configuring a cluster. Please contact the
authors for a detailed description if you want to get the most out of PHPGallue.