************************************************************** * 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//pub/PHPGallue/*/htdocs/* ~/public_html/PHPGallue/ # link regular scripts ln -s /home//pub/PHPGallue/*/admin/* ~/public_html/PHPGallue/admin/ # link admin scripts If everything worked as expected, you can run the setup script at http://localhost/~/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//public_html/ and you want to install the library files to /home//pub/PHPGallue/. The cache directory will be at /home//pub/cache/gallue/ and the config file at /home//pub/config.xml. Please replace 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. 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 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//pub/PHPGallue/*/htdocs/* ~/public_html/PHPGallue/ # link regular scripts ln -s /home//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/~/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//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//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//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:///~/PHPGallue/". Replace and 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//. 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.