README -- ThumbNails 3.0
------------------------
Copyright 2001, 2002 by Al Evans
--------------------------------------------------------------------------
|ThumbNails is released under the terms of the "Artistic License". Please|
|see the file LICENSE in this distribution for complete definitions of |
|these terms and conditions. |
_________________________________________________________________________
ThumbNails is a system of perl scripts for setting up and maintaining a web
site containing a large number of digital photographs. It will make a
thumbnail image for each picture, create a "thumbnail index" page of thumbnails
that act as clickable links for each picture, and create an overall top-level
index page with a clickable link to each of the thumbnail index pages.
ThumbNails can interact with a MySQL database server, permitting the addition
of captions, short names to replace the pictures' file names, section names to
replace their directory names, dates, credits, and copyright information. The
data associated with each picture can be edited remotely, via the web.
ThumbNails includes a daemon which monitors the configuration file, the
pictures directory, and the database, and automatically reflects changes in any
of them into the "remote user" view.
An example can be seen at <http://www.alevans.com/ImageTest/TNDB>.
-------------------
System Requirements
-------------------
ThumbNails should work on almost any UNIX or UNIX-like system. It requires perl
5 (which you probably have, but if you don't, you should get it from
<http://www.perl.org/>). It also requires the ImageMagick (TM) tool "convert",
which is used to make the thumbnail images. This tool, and the rest of the
ImageMagick software, can be obtained from <http://www.imagemagick.org/>.
NOTE: Because of the use of ImageMagick's "convert" tool, ThumbNails is limited
to the types of image files this tool can process. But note that web browsers
are even more limited in the kinds of images they can display!
Both of these software packages are included with RedHat linux (versions 6 and
7), and probably with many other popular versions of linux.
It should be obvious that you need a web server running in order for anyone
beyond your local machine to see your pictures. You also need write access to
the location in the web hierarchy where you want to install the images.
In order to use the optional database connection, you'll need the MySQL server
software (available from <http://www.mysql.com> installed and running. You'll
also need authority to create new databases and users. And you'll need the
"DBI" module for perl.
You will need authority to install scripts into the cgi-bin directory of your
webserver, in order to edit the picture information over the web and
incorporate it into the pages sent to remote users. In addition, you'll need
the perl "CGI" module.
You can determine whether the necessary perl modules are installed by using the
commands:
find `perl -e 'print "@INC"'` -name '*.pm' -print | grep CGI.pm
and
find `perl -e 'print "@INC"'` -name '*.pm' -print | grep DBI.pm
If these commands succeed, i.e. if they print out pathnames, then you have the
modules you need. Otherwise, you'll need to install them -- you can get both of
them at <http://www.cpan.org>.
--------------------------------------
Setting Up The Basic ThumbNails System
--------------------------------------
First, set up your pictures directory
-------------------------------------
ThumbNails works with a directory containing directories full of pictures, like
this:
$pixDirPath (e.g., /home/pictures)
_______________________________________|___________________________(...etc.)
| | | | |
picture picture picture picture picture
directory directory directory directory directory
| | |
subdirectory subdirectory (...etc.)
Each picture directory may contain pictures, along with one or more
subdirectories which also contain pictures and/or other subdirectories
containing pictures. There's no theoretical limit, but the layout should be
kept simple for easy navigation by the web user.
IMPORTANT NOTE: The top-level directory, $pixDirPath, may NOT itself contain
any pictures. All pictures must be placed in directories BELOW $pixDirPath in
the directory hierarchy.
Decide where in your web hierarchy you want to install the pictures. You will
need to enter the actual pathname ($webRootPath) (e.g., "/home/me/public_html")
and how to refer to this location in a relative URL ($webRootRelURL) (e.g.,
"/~me").
Note that directory permissions for the pictures directory and its
subdirectories should be 755, and file permissions for all files in the
hierarchy should be 644, to allow the necessary access via the web.
Second, edit LocalConfig.pl as needed
-------------------------------------
If you are updating a previous version of ThumbNails, copy the file
LocalConfig.pl from it to your new ThumbNails v3 directory and type
./UpdateConfig.pl. (As an alternative, you can type
./UpdateConfig.pl to update it in place.)
Your configuration file will be backed up to LocalConfig.pl.orig, then updated
to the current version. Look at the new variables $combineLevelsBelow,
$thmbnlMainIndexDepth, $thmbnlIndexReverseSort, $thmbnlSubDirReverseSort,
and $thmbnlsReverseSort and make sure they're set as you want them.
If you are installing ThumbNails for the first time, you will need to
cp ./LocalConfig.rel ./LocalConfig.pl
and edit ./LocalConfig.pl to set the following variables to appropriate
values:
Set $webRootURL to the top-level URL for your web site, for example,
"www.yourdomain.com".
Set $pixDirPath to point to your pictures directory, for example,
"/home/pictures".
Set $webRootPath to the pathname where you want the pictures directory
installed in your web hierarchy, for example, "/home/httpd/html". Set
$webRootRelURL to the URL, relative to the top of the web hierarchy, for this
same location (in this case, since /home/httpd/html IS the top of the
hierarchy, $webRootRelURL would be "").
Set $webPixDirLinkName to the name you want your pictures directory to have on
the web, for example, "Pictures".
Set $thmbnlHTMLDirName to the name you want to give the directory which will
hold the HTML pages of thumbnails for your site. This directory will be created
at the top level of the pictures directory.
If you want to use the CGI script provided to display your images in a nice
background, instead of in the upper left corner of the browser window against a
stark white background, set $useCGI to 1. You should also set $cgiBinURL to
point to your cgi-bin directory.
If you want to use the MySQL database features, set $useDB to 1, and set
$imageDBName to the name you want to use for your pictures database. Note that
the database features won't be much use unless $useCGI is also 1!
By default, ThumbNails is set up to produce one page of thumbnail images for
each directory under $pixDirPath, regardless how deep it is nested, and to
put an entry into the main index for the site (index.html) for each page of
thumbnails. This behavior can be changed by editing the variables
$combineLevelsBelow and $thmbnlMainIndexDepth.
By default, ThumbNails sorts index entries, subdirectories, and thumbnails in
normal alphabetical sort order. The sort order of each can be reversed by
editing the variables $thmbnlIndexReverseSort, $thmbnlSubDirReverseSort, and
$thmbnlsReverseSort.
Down at the bottom of the variables section in LocalConfig.pl is
@protectedDirs. This is a list of directory names under the main pictures
directory that will be ignored by ThumbMails. You shouldn't remove either of
the variables from this list, but feel free to add more directory names to it.
Note, however, that any directories under $pixDirPath can be read by anybody --
since $pixDirPath is on the web, they are LITERALLY world-readable!
Most of the rest of LocalConfig.pl shouldn't require editing, but feel free to
change things if you want.
You can experiment with these configuration settings as much as you want. Just
delete all the .html files and run ThumbNails again. The site will be rebuilt
with your new settings in effect.
Third, run ThumbNails
---------------------
You will see progress reports as ThumbNails builds your web site. If everything
goes well, it will finish by printing the URL of the completed site. Paste it
into your browser and check it out.
If you're using the CGI features ($useCGI = 1), copy picframe.cgi (and/or
picframeDB.cgi, if you plan to use the database features) and picframe.tmpl
into your cgi-bin directory. These files are in the directory move.to.cgi-bin.
If you add, delete, or change pictures, just run ThumbNails again. It should do
only what needs to be done to bring the site up to date. But see "Automatic
Maintenance" below!
The files "TN.tmpl" and "TNIndex.tmpl" are template files that control the
overall appearance of the thumbnail pages and the index.html page,
respectively. Similarly, "picframe.tmpl" is the HTML template used by
picframe.cgi and picframeDB.cgi. They are all regular HTML files. The HTML
comment in each of them is replaced with code generated by the
scripts. Feel free to edit them as you wish.
-----------------------
Setting Up The Database
-----------------------
Preliminaries
-------------
You will need "ALL PRIVILEGES WITH GRANT OPTION" in MySQL In order to run the
setup script successfully!
Be sure you've got LocalConfig.pl edited to your taste, that you've set
$useDB=1, and that you've set $imageDBName to the name you want to give your
pictures database.
Database Setup
--------------
After you have the basic ThumbNails system configured and working, run
TNDBSetup.pl to set up your ThumbNails database. This script will ask for three
pieces of information:
1) A user name for a remote user authorized to maintain the picture database
over the web,
2) A password for this user,
3) A pathname for the HTML page that will be created to allow the remote user
to log in to the database.
The user specified in 1) will be added to MySQL's user list, with authority to
perform INSERT and UPDATE commands on the ThumbNails database. You should NOT
use your own user name and password for this purpose! Working with databases
over the web is NOT SECURE, and cannot easily be made so! The remote user
specified above will be granted only limited access to this specific database,
without the option of granting this access to others.
TNDBSetup will create the necessary database, add the specified user, write out
a login page, and write out a file containing this user's login name and
password (TNDBRemoteUser.cnf) to permit automatic maintenance of the database.
After running TNDBSetup, the next step is to copy the necessary files to your
cgi-bin directory. The files that need to be copied are:
TNDBLogin.cgi and TNDBIndex.tmpl
TNDBThumbnails.cgi and TNDBThumbnails.tmpl
TNDBEditPic.cgi and TNDBEditPic.tmpl
TNDBErr.tmpl
TNDBSectName.pl
TNDBCommon.pl
These files are in the move.to.cgi-bin directory.
At this point, you should be able to point your browser to the login page, log
in, and start working with the database.
If you want other viewers to see the names and captions you've added:
-- Copy picframeDB.cgi and picframe.tmpl to your cgi-bin directory, if you
haven't already done so.
-- Be sure that $useCGI = 1 in LocalConfig.pl.
-- Force ThumbNails to rebuild its HTML thumbnail indexes by deleting
everything in $pixDirPath/$thmbnlHTMLDirName (for example, "rm
/home/pictures/Thumbnails/*". If the ThumbNails daemon is running (see below),
it will rebuild the HTML pages the next time through. Otherwise, do it manually
by typing ./ThumbNails.
---------------------
Automatic Maintenance
---------------------
After you have everything working like you want it, you can configure and start
TNDaemon.pl. Actually, the only things you might want to "configure" are the
frequency with which it checks the pictures directory (by default, it waits 120
seconds between runs), and the name of the file to which it logs actions.
This daemon checks LocalConfig.pl and the pictures directory every few minutes.
If anything has changed, it rebuilds the thumbnails, thumbnail HTML pages, and
the index file as required. If the database feature is being used, it will
resynchronize the database with the pictures directory as needed.
KillTNDaemon.pl will stop the daemon.
------------------------------------------------------------------------------