$Id: Install.txt,v 1.21 2000/12/21 08:56:52 dan Exp $



MiG - A general purpose photo gallery management system.

Copyright (C) 2000 Daniel M. Lowe	<dan@tangledhelix.com>


LICENSE INFORMATION
-------------------

This program is free software; you can redistribute it and/or
modify it under the terms of the GNU General Public License
as published by the Free Software Foundation; either version 2
of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
GNU General Public License for more details.

You should have received a copy of the GNU General Public License
along with this program; if not, write to the Free Software
Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA  02111-1307, USA.

A copy of the GPL can be found at http://www.gnu.org/copyleft/gpl.html
or in the file docs/License.txt.


REQUIREMENTS
------------

This package requires a web server which supports PHP (http://www.php.net).
Any recent version of PHP3 or any version of PHP4 should work.  The
development platform is Linux, so this code tends to assume a Unix-like
environment.  As such it may or may not work (and has not been tested) on
non-unix-like platforms.  This package is developed using PHP3 and does not
have any PHP4-specific code.  Currently I am developing under PHP v3.0.16.

(Windows users, please see the file "docs/Windows.txt" for more information.)

(PHP-Nuke users, plase see the file "docs/phpNuke.txt" for more information.)

The "mkGallery" utility (used to generate thumbnail images) requires Perl
(http://www.perl.org) and ImageMagick (http://www.imagemagick.org).
You can use MiG without Perl or ImageMagick - but in that case you may
have to create your own thumbnails and not use mkGallery.  See the file
docs/Utilities.txt.  Since thumbnails are optional, you don't even need to
generate them if you don't want to or it's not convenient for you.

The "jhead" utility which is called by mkGallery for EXIF header parsing is
a C source code file - you will need to compile it before using it.  See the
file "docs/Utilities.txt" for more information.  Since "jhead" is also
optional you don't need to worry about this if you don't plan to extract
embedded comment information from your JPEG files.



INSTALLATION AND BASICS
-----------------------

Installation is fairly straightforward.

1. Unpack this archive and enter the resulting directory.

     gzip -dc mig-1.1.tar.gz | tar xf -
     cd mig-1.1

   (If you're using Windows you will perhaps want the .ZIP file available
   at the same location as the .tar.gz files.)

2. Run the install script "install.sh" and follow the directions.

     ./install.sh

3. Enter the installation directory (which you specified during the
   installation).

     cd /usr/apache/htdocs/mig

4. Review the file "mig.cfg.default".  If you want to make any changes,
   make them and then copy the file to "mig.cfg".  The reason to do this
   is simple: future installations / upgrades will copy over mig.cfg.default
   with whatever is packaged with that version of MiG.   The mig.cfg file
   will never be automatically over-written by the install script.

     vim mig.cfg.default
       [ or if you are a heathen, use some other text editor :-) ]
       [ make desired changes ]
     cp mig.cfg.default mig.cfg

   Or, if you are upgrading, it's a good idea to review mig.cfg.default to
   see if there is anything new that you will want to add to your mig.cfg.

5. Enter the albums directory.

     cd albums

6. Create any folders and subfolders you want for your own albums, and
   copy your images into them.

     mkdir Trips
     mkdir Trips/Alberta,_Canada
     mkdir Trips/Lake_Tahoe,_California

     mkdir House
     mkdir House/Living\ Room
     mkdir House/Dining\ Room

   You can of course, also do this with FTP, scp, or your favorite file
   handling method.

   A note about spaces in gallery names:  If there is a space embedded in
   the directory name, it is left as a space.  If there's an underscore (_)
   in a directory name, it is displayed to the viewer as a space.  So you
   can use whichever you like in your galleries and both will appear to be
   a space as far as the browser is concerned.

   A note about files:  Basically, any PNG, JPG or GIF file will be shown.
   That is, any file with an extension of .gif .jpg .jpe .jpeg or .gif.
   Note that case is irrelevant so ".GIF" is the same as ".gif" or ".Gif".

   A note about file permissions: MiG makes no attempt to modify or check
   the file permissions in your album subdirectory.  It is left to you to
   make sure the web server has the ability to read these files.  On most
   systems this means making sure the directories are at least 0755 (which
   is drwxr-xr-x) and files are at least 0644 (-rw-r--r--).  However, many
   people run their systems in such a way that those modes are considered
   dangerous to them, and I don't make any assumptions.  Please validate
   the permissions on your albums to make sure the web server has access
   to read them.

   MiG does set file permissions on the files it actually installs (the
   PHP files themselves, mig.cfg.default, the templates, etc).  If these
   are unsatisfactory to you (they should be perfectly fine for everyone
   as far as I can see), please let me know, and of course you can reset
   their permissions as you see fit on your system.

   Thumbnails are basically seen by MiG as anything that matches the basic
   pattern "filename_th.EXT"... so myhouse_th.gif will be viewed as a
   thumbnail.  The basic rule of thumb is, try not to use the string "_th"
   in your filenames.

   **  Note, as of 0.90 this behavior changed.  This is still true of the
   **  default settings, but you now have the ability to control the format
   **  of thumbnail filenames.  See docs/Utilities.txt and mig.cfg.default.

   You can use spaces (or, as above, underscores) in filenames just like
   you can do with directory names.  Underscores in filenames will be
   shown as-is though, they are not re-mapped to be displayed as a space.

   Also, thumbnails can live in a subdirectory rather than in the main
   folder - see below under "Optional Customization".

7. You probably want to create thumbnails.  You can use the mkGallery
   script found in the "util" subdirectory.  Note that it requires Perl
   and the ImageMagick suite (see the file docs/Utilities.txt).

   You don't have to use mkGallery - you can make your own thumbnails if
   you want.  Just have the filenames match the pattern shown above.  So...

     myHouse.jpg	= myHouse_th.jpg
     Livingroom.JPG	= Livingroom_th.JPG

   Case does matter for the "_th" - it must be lowercase!

   To create thumbnails, in a nutshell:

     cd /usr/local/apache/htdocs/gallery/Trips/Lake_Tahoe,_California
     ../../util/mkGallery -a -t

   See the file "docs/Utilities.txt" for more about mkGallery.  You can get
   a listing of available options by invoking "mkGallery -h".

   The author finds 'mkGallery -rant' to be the most useful mode for
   general purposes.  Again, see docs/Utilities.txt for more information.

   **  Note that not all thumbnails have to use _th as their "unique" part
   **  anymore.  See docs/Utilities.txt.  You can make them anything you
   **  want, and can even "prefix" them to the filename instead of suffixing
   **  them.

   For mkGallery to create thumbnails, "convert" from the ImageMagick suite
   must be in your $PATH.

   If you elect not to use thumbnails, a generic "image" icon will be
   used in place of a thumbnail image, so creating thumbnails is not
   mandatory (it just makes for a nicer presentation for people viewing
   your album).

   mkGallery will only bother with the PNG, GIF or JPEG files it finds
   in the current directory (.gif .jpg .jpe .jpeg and .png).

   As of version 1.1, you can use a thumbnail subdirectory rather than
   having your thumbnails co-exist in the same folder with the images
   they represent.  See below under "Optional customization" for more info.

   As of version 1.1, you can use a global thumbnail extension for all
   thumbnails.  For example if you want all thumbnails to be GIFs even
   if the real images they represent are something other than GIF,
   you can do this.  See the "-E" option to mkGallery, and the $thumbExt
   option in mig.cfg.  Also see docs/Utilities.txt.

8. Go to http://www.yourserver.com/mig/ (or wherever you happened to
   install it) to view your gallery with your web browser.

   You may have to tell your web server that "index.php" (or index.php3)
   is a valid default page.  Apache users will need to add the filename
   to the "DirectoryIndex" directive (adding to the end of the line in
   your httpd.conf and running "apachectl graceful" as root is probably
   the way to do that).  Other changes to Apache might be required to
   support PHP.  How to get PHP to work in general is left as an exercise
   to the reader, but www.php.net and www.apache.org should have the
   information needed.


OPTIONAL CUSTOMIZATION
----------------------

1. HTML templates (and colors)

   You may optionally edit the HTML templates found in the "templates"
   subdirectory.  See the file docs/Templates.txt for more information.

2. Hidden folders and hidden files

   If you have some reason to hide particular files or folders from general
   view (i.e. it can be viewed but only with an exact URL, you don't want
   people wandering in there from the general public) you can list those
   items in a file called "mig.cf" in the relevant folder.  As an
   example, look at "albums/Example_Gallery/mig.cf" (if you installed the
   Example Gallery).

   To add hidden items, just add a <Hidden> element, like this:

     <Hidden>
     hidden_folder
     another_hidden_folder
     </Hidden>

   Users of Apache will find this configuration format pretty familiar.
   Tag elements like <Hidden> must be at the beginning of a line!

   See the file docs/mig_cf.txt for information about the format of mig.cf.

   (Note for users upgrading from MiG 0.83 or earlier - the format has
   changed, as you'd have noticed already.  If you need to convert to the
   new format, use the "convert-metafiles" script which is in the contrib
   section on the MiG home page).

   Note that Hidden is not considered "secure".  If you need to make sure
   your gallery is secure, please take advantage of the password protection
   in your web server (if it has such a feature).  You can also take
   advantage of MiG's built in password features (see docs/Passwords.txt).

3. Comments

   You can optionally add comments for any image you wish.  You don't have
   to add comments at all.  The comments are stored in "mig.cf" in the
   same directory as the image in question.

   Comments are shown in a box below the image in image views.  In
   thumbnail views, they are shown as the ALT tag text.

   As an example, let's say you had files "house.jpg", "car.gif" and
   "dog.jpg".  Let's say you wanted a comment on the house and the dog,
   but nothing in particular to say about the car.  You would add markup
   like this to mig.cf:

     <Comment "house.jpg">
     This is my house, which I bought in the fall of 1998.
     </Comment>

     <Comment "dog.jpg">
     This is the dog we had when I was growing up.  She was a lot of
     fun!  Sadly, she died when I was 12 years old (she had cancer).
     We had other dogs afterward, but none of them were as much fun.
     </Comment>

   (If you want to save yourself some typing you can use the "-c"
   option to util/mkGallery to create a blank comments template.  You
   can also use the "-i" option to enter comments interactively.  See
   docs/Utilities.txt for more information.)

   You can have as many lines as you want for the description.  The key
   is that the description must be enclosed inside the
   <Comment>...</Comment> structure.  The tags such as <Comment> and
   </Comment> MUST be at the start of a new line.
   
   There are examples in albums/Example_Gallery/mig.cf (if you installed
   the example gallery).

   See the file docs/mig_cf.txt for information about the format of mig.cf.

   (Note for users upgrading from MiG 0.83 or earlier - the format has
   changed, as you'd have noticed already.  The install script probably
   already updated your metafiles such as .comments.txt but if not, you can
   do so by hand by running convert-metafiles which is in the contrib
   directory on the MiG homepage).

4. EXIF header information

   You can build EXIF comment files (exif.inf) using mkGallery and the "-e"
   option.  See the file docs/Utilities.txt.  Note that you must compile the
   (included) "jhead" utility from Matthias Wandel before the -e option
   will function.  Compiling jhead is probably as easy as this:

      cd util/jhead ; make clean ; make

   Since only JPEG files support EXIF headers, mkGallery will only look
   at JPEG files when building the EXIF files.  Much more than the
   comments themselves are stored in these exif.inf files, and future
   versions of MiG may parse more information from these files than it
   currently does.  Right now all MiG knows how to extract from the
   exif.inf file is embedded comments.

   (Note for users upgrading from MiG 0.83 or earlier - the filename has
   changed, as you'd have noticed already.  The install script probably
   already updated your metafiles such as .exif_comments.txt but if not,
   you can do so by hand by running convert-metafiles which is in the
   contrib directory on the MiG home page.  The only change for EXIF files
   is the filename, just rename to 'exif.inf').

5. Style sheets

   You can modify the file templates/style.css if you want to change the
   text/css style (which is what determines link coloring).  If you don't
   want to use the style.css file, remove the #include directive from
   the HTML templates which includes it in the template.  For more
   information see docs/Templates.txt.

6. Item sorting

   You can define your own sort order (rather than relying on alphabetical
   sorting) - see docs/mig_cf.txt.

7. Symlinks

   You can create virtual collections and cross-linking among your albums
   by simply using symbolic links.  For instance you can do stuff like:

     cd albums
     mkdir People ; cd People
     mkdir Katie ; cd Katie
     ln -s ../../Birthdays/Katie_2000 .

   And you end up with the "Birthdays : Katie 2000" folder as a "virtual"
   folder under the "People : Katie" folder.  In this way you can have a
   folder in more than one place at the same time without having a need for
   more than one copy of the photo on the disk.

   I have only tested that under Apache with PHP3.  And of course it
   probably won't work in Windows because as far as I know, FAT32 and
   NTFS do not support symbolic links in the first place.  I do not know
   if Windows shortcuts (.LNK files) will work instead.

8. Thumbnail image information

   Some people may not like to have the "540KB, 640x480" type stuff to
   be displayed below each thumbnail.  If you don't want it there, see
   the $suppressImageInfo option in mig.cfg.default.  Setting that to
   TRUE has the effect of showing thumbnails as images only - no other
   information is shown about each image.

9. For Apache users only

   If you are using the popular Apache web server, see docs/Apache.txt
   for some useful Apache-specific tips and tricks.

10. Password protected folders

    MiG can password-protect folders, or collections of folders.  See
    docs/Passwords.txt for more information.

11. Thumbnail subdirectories

    Some users don't like having their thumbnails littering up their
    folders alongside their images.  For those users, the $useThumbSubdir
    option exists.

    Basically to use this, one would create a subdirectory in each folder
    (perhaps called "thumbs").  Thumbnails in that subdirectory would have
    the exact same name as their full-size counterparts in the main folder.
    This is different than the old behavior where you were forced to use
    two different filenames.

    See docs/Utilities.txt for information about this option and mkGallery.
    Also see mig.cfg.default for the $useThumbSubdir and $thumbSubdir
    parameters.  By default, thumbnail subdirectories are not used (for
    historical reasons).

12. Thumbnail suppression

    Some people don't want to have thumbnails whatsoever.  For those people
    the $noThumbs switch exists in the mig.cfg file.  Setting $noThumbs to
    TRUE has the effect of not using thumbnail images at all in your
    albums.  $noThumbs is set to FALSE by default.

13. Forcing a thumbnail type

    Some people expressed a desire to have all thumbnails be a certain
    type no matter what their normal images were.  For example, main
    images might be JPG or GIF but all thumbnails would be GIF,
    regardless.

    By default, if an image is a JPG, MiG will also look for a JPG
    thumbnail.  A GIF image will have a GIF thumbnail.

    If you wish to use all the same type for thumbnails even if the
    real image is a different type (or varying types), set the value
    of $thumbExt in mig.cfg to the extension you are using.  Note that
    case does matter, so setting it to "gif" and uploading foo.GIF
    will result in an error!


BUG REPORTING
-------------

Report any bugs to mig-bugs@tangledhelix.com. 


EMAIL LISTS
-----------

There are two email lists for MiG users.  Visit the indicated URLs for more
information about each list.

  Announcements only	http://snoopy.net/mailman/listinfo/mig-announce

  General discussion	http://snoopy.net/mailman/listinfo/mig-users

