Virtual Photo Album (vphotoalb)
===============================

Install as follows:

Copy PHP Scripts to Web Server
------------------------------

vphotoalb requires a working web server with PHP capabilities.  Copy all of the
files located in the html directory to some directory (say 'album') accessable
by the web server.  When this is done, you should be able to access the web
pages through your browser and get a bunch of database errors.  If you get an
error such as '404 Not Found' or permission denied errors then you should
verify that the web server can indeed access the files.  Some web servers may
use index.php as opposed to index.php3 as a default page for a directory.  If
this is the case, rename index.php3 to index.php in both the root directory
and the admin directory.  

If, instead of the php3 page getting executed, it is offered by the web server
for download (or displayed in your browser window), then your server does not
have a functioning PHP engine installed.  Consult your web server documentation
or the PHP documentation to solve the problem.

After installing the php3 files, you will most certainly need to edit the file
constants.php3 and admin/constants.php3.  You should also check db.php3 and
admin/functions.php3 to verify that vphotoalb is set for the correct type of
database server you have (currently, PostgresSQL or MySQL).  If you are porting
this software to another environment, you will likely need to modify
functions.php3 in addition to the files already mentioned.  To customize the
help messages, edit help.php3.


Create Database Tables (easy method)
------------------------------------

It seems that there are, understandably, people out there who would like to use
this software but lack experience setting up a database.  Therefore, to make
setup and upgrade of the database easier, there is now an automated setup
script in the admin section of this software.  To use it, you need to first
ensure that:

  1. the php3 files are installed as described above
  2. your database software is installed and a database has been created for
     use by the album (the tables get installed below)
  3. you have edited constants.php3, db.php3, and admin/features.php3 to set
     the database specific parameters (type, location, password, etc)
  4. you have edited admin/constants.php3 to set the security such that you can
     access the admin section (see docs/security.txt)

If all goes well, you should be able to point your web browser at the admin
section with:

  http://server_name/path_to_album/admin/

and get the index page.  If all you get is a database error, step 2 above is
not complete.  If you get an index page with a bunch of links, don't worry about
any database errors in the status section that might appear.  Follow the link
for 'Install/Upgrade/Check Database'.  This should take you to a page indicating
that the required tables have not been installed yet.  You will find a link to
confirm that you want them installed, follow it.  This should take you to a
page indicating that the tables were successfully installed.  If you have
problems at this point, you may need to try one of the manual methods below,
talk to your database administrator, or you can email me and I'll try to give
you some useful advice.  

Upgrading from a previous version:

After installing a new version of the virtual photo album software, always go
to the 'Install/Upgrade/Check Database' page in the admin section to see if
any new fields need to be added to your database tables.  The page should allow
you to painlessly add the fields without any loss of data in your current
database.

If this automated database setup page has worked for you, you can skip the
'manual method' sections below.  Proceed to the section on creating photos.


Create Database Tables (PostgresSQL manual method)
--------------------------------------------------

You will need to create a new database for use by vphotoalb.  Assuming you have
PostgresSQL installed and functioning, use the command 'createdb' to create a
new database.  For example:

  createdb album

will create the database named 'album'.  The file constants.php3 contains the
name of the database vphotoalb will attempt to connect to.  Once the database
is created, you need to add the tables.  Change to the directory 'sql/postgres'
from the vphotoalb distribution and run:

  cat create-tables.sql | psql album

where 'album' is the name of your database.  If you are upgrading from a
previous version of vphotoalb, the format of the database tables may have
changed.  If this is the case, you may need to:

  cat upgrade-from-m.n.sql | psql album

See the NEWS file for more details.

Finally, your web server needs access to the tables.  If your web
server does not run under the username 'nobody', you will need to edit the
file permissions.sql and change 'nobody' to the name your web server runs as.
Then execute:

  cat permissions.sql | psql album

If this command fails, the user your web server runs under may not be known to
the PostgresSQL database engine.  You can try:

  createuser nobody

and then rerun the permissions command above.  If this fails, contact the 
administrator of your PostgresSQL database for help.


Create Database Tables (MySQL manual method)
--------------------------------------------

I'm not very experienced with MySQL so this section will be pretty short.  In
the directory sql/mysql you will find the SQL commands needed to create the
three tables used by the album.  Use the 'mysql' utility to create the tables.
You will need to ensure that the web server has the appropriate permissions to
access the database.  Edit the file 'constants.php3' to set the various
parameters needed for access to the database server.  Make sure 'db.php3' is
set to use MySQL.  If you are upgrading from a previous version of vphotoalb,
you may need use one of the upgrade-from-m.n.sql files to upgrade your database
format.  See the NEWS file for more details.


Populate pictures and movies Directories with Photos
----------------------------------------------------

The 'pictures' and 'movies' directories should contain a bunch of
subdirectories representing collections of photos (or movies).  Within each
subdirectory under 'pictures' there should be 3 versions of each photo.  Photo
'p01423' needs three files as follows:

  p01423t.jpg - thumbnail
  p01423l.jpg - little photo
  p01423b.jpg - big photo

Under 'movies', each subdirectory should contain two files for each movie.  For
movie 'm00543', you need:

  m00543t.jpg - thumbnail
  m00543.gif  - animated gif (the movie)

Bourne shell scripts are provided in the scripts directory to automate the
creation of the image files described above.  These are the scripts that I use,
but are not documented so if you choose to use them, you are on your own.  Use
of these scripts is optional.  You are free to choose any means you like to
create the necessary files.


Use Admin Menu to Add Entries to Table of Contents
--------------------------------------------------

When adding TOC entries using the admin menu, keep in mind that 'collection'
refers to the name of the subdirectory you created in 'pictures' or 'movies'.
You must type the collection name such that it _exactly_ matches the name
of the subdirectory you stored the pictures in.  First date is manditory, but
last date is optional (it will be set the same as start date if left blank).
Major category should probably be set (see docs/categories.txt), but minor
category is unimplemented at the present time and can be ignored.  Collection,
once set, should never be changed as that would break any captions or custom
TOC entries setup by your users.  In the near future there will be another 
description field for short description (similar to collection, but without
the rigidity of collection).  


These steps should be all that is required to get your Virtual Photo Album
working.  In the future, documentation will be provided to cover the more
advanced features of the album.  For now, you will need to learn through
exploration.  If anyone is willing to write documentation, let me know.


