PhotoAlbum Manual

What is it?

a Flickr alternative, if you have some space on a server and like to be in control of your own photos
or a convenient way to catalog and view photos on your own machine
it's free software and the source code is available (GPLv3)
a web app to run in tomcat (or other java web server) that displays images
images viewed medium size with commentaries, full size and thumbnails
wysiwg html editing of commentaries
images can be placed in one or more categories
three levels of access:-
1. admin - full view/edit/enter/delete access
2. user - view/edit access to allocated categories
3. guest - has access to "public" photos (no login necessary)
admin user has onscreen view of access and edit log data
choice of database backends - hsqldb (built in default) and mysql
export of data to xml
import data from xml - to avoid database lock in
built using grails (apache license) with the FCKeditor plugin(apache/GPL/MPL)

What's Needed

a running java web server such as tomcat
on a machine with sufficient RAM, probably 500MB minimum
images files arranged to suit (see getting started)

Getting Started

preparing the image files - the painful bit:-

all files must have the same case sensitive extension ie jpg/JPEG etc
they should be in subdirectories of a single directory
each subdirectory should contain:-

the full sized images
a directory med, containing medium size/quality reductions - suggest up to 600px dimensions/150KB
a directory tn, with thumb nail reductions

on a Gnu/Linux system webnail will do this for you

the rest is easy! download the war archive from sourceforge
rename PhotoAlbum-1.x.war to PhotoAlbum.war and copy it to the tomcat webapps directory
when tomcat runs it unpacks the archive to webapps/PhotoAlbum; either:-

copy all your image subdirectories to webapps/PhotoAlbum/Album
or with tomcat 7 and later configure it to look for the images on your file system ie:-

in conf/context.xml you need:-

		<Context path="/PhotoAlbum" aliases="/Album=FULL_PATH_TO_YOUR_IMAGE_DIRECTORY">
		    <WatchedResource>WEB-INF/web.xml</WatchedResource>
		</Context>

and restart tomcat

browse to http://localhost:8080/PhotoAlbum (assuming you're testing on your desktop machine)
login as admin with password password
the directory the app is using to write it's files to is recorded in red; some files will be in the photoalbum subdirectory
with a text editor (not a word processor) edit the file photoalbum.cfg in that directory
the second line, jpg as default, tells the app what filename endings your images have
if necessary edit that line, save the file and restart either the app or the tomcat server

using PhotoAlbum

if you don't have a password, login as guest (no password)
in categories, click the single entry - public, by default, but it may have been renamed
the administrator may have configured things to make other categories accessible
click on one of the thumb nail images

you can Zoom to see the image full size; Previous and Next allow you to cycle through the category
since this photo is in the public category, you could browse straight to it at http://localhost:8080/PhotoAlbum/photo/show/1
you can also browse directly to categories that guest has access permission
if the admin has made an account for you, instead, log in with the credentials you've been given
there may be other categories beside those available to guest, if the admin has allowed that
again select an image, this time there will also be an Edit button, which takes you here:-

you can edit the commentary using the html markup tools
there is a limit of 1000 characters and some of that may be used by invisible html markup
you can use the Insert/Edit link tool to link to other photos, or any other site
to link to another photo just specify it's number (end of address bar), Link Type should be URL and Protocol is other
Update the commentary to save your edit

PhotoAlbum administrator

managing users

the admin user sees additional information to other users
the working directory specifies the location of hsqldb database files; log, config and exports are in the photoalbum subdirectory
the log records logins, logouts and commentary edits
you can remove these details with the Clear logs button
if you run this on a public facing server, select users and edit your own credentials; the login name does not have to be admin
you can also add, delete and edit other user accounts
the admin user automatically gets access to all categories, the guest user automatically gets the default public category
public, but not guest may be renamed
when creating or editing other users, you select the categories you wish them to have access to

to highlight more than one category use the Ctrl key as you click

managing categories

this is similar to managing users

here by pressing Update, admin and friend users will have access to the friend's photos category, which has just the single photo

adding photos the slow way

select photos and then New Photo

you must specify the Title as the filename without the extension (ie leave off .jpg) and the Directory
adding the photo to a Category is optional at this point and the Commentary can be left blank
click Create to save

editing photos

the admin user has extra options compared to limited users

if you just want to add or edit the Commentary, use the Update the commentary button
if the filename or directory has been changed, you can adjust that here
use the Update all button, first reselecting the categories, or existing one's will be lost
as expected, when viewing the photos, the admin user has an additional Delete button

adding photos the fast way

first you must edit your photoalbum.cfg in the working directory again
the 6th line must contain the actual full path on your file system to your images directory
the path must end with a final path separator ie / or \, depending on your system
select Insert directory to get a list of all the subdirectories that have no photos inserted

use the radio buttons to select one of the directories and click the Choose button

assuming you wish to insert this photo, press Insert rather than Skip, having first ticked the appropriate Category checkboxes
the photo will be inserted and the next photo in the directory presented to be dealt with

exporting the database

select export database from the Home screen
the database is exported to the working directory as User.xml, Category.xml and Photo.xml

importing the database

the three xml files must be available and the app must be running with an empty database
stop the app or tomcat and remove the hsqldb files from the working directory, ie PhotoAlbum_prod.log and PhotoAlbum_prod.properties
restart tomcat and the app, log back in with admin and password and select import database
after a considerable pause (30 secs?) and with a following wind :), the database will be imported

if it fails the log should give an indication where
on a much-edited database, the order of categories in Category.xml did not, on one occasion, reflect the order in the database
with the help of the log you can edit the appropriate xml file, empty the database and try again
note that to protect the database, importing fails harmlessly if there are any inserted photos
the Clear the log file button will remove the details from the Home screen

switching to mysql

It's unlikely this will be necessary as the built in default hsqldb database should be adequate. If your superb photos attract lots of viewers or you are running mysql anyway, you may want to switch. If you already built up a sizable database the export / import facility is your friend. You can prepare mysql by entering the commands below:-

mysql -u root -p;
enter your mysql password
create database PhotoAlbum_prod;
case *is* important here
the photoalbum user must be created with an empty password:-
grant all on PhotoAlbum_prod.* to 'photoalbum'@'localhost' identified by '';
flush privileges;

The necessary tables will be created by the application when it's first run, but these are massively oversized.

You can tune the database (described below) once the tables have been created or insert the supplied empty database from the OS command line with
mysql -u photoalbum PhotoAlbum_prod < PhotoAlbum_empty

export the database as above
stop tomcat or the web app
edit the 4th line of photoalbum.cfg in the working directory from hsqldb to mysql
restart tomcat / the app
import the database as above

Tuning mysql

Unless your running some other database that needs it, turn off Innodb. Edit my.cnf and uncomment (or add) the line skip-innodb. For reference this is how the default mysql database that grails creates can be tuned:-

Enter mysql from your OS command line:-
mysql -u photoalbum
Then at the mysql prompt, these commands:-

use PhotoAlbum_prod

ALTER TABLE category MODIFY COLUMN id tinyint(2) AUTO_INCREMENT;

ALTER TABLE category MODIFY COLUMN version smallint(5) NOT NULL;

ALTER TABLE category MODIFY COLUMN title varchar(20);

ALTER TABLE photo MODIFY COLUMN id smallint(5) AUTO_INCREMENT;

ALTER TABLE photo MODIFY COLUMN version tinyint(2) NOT NULL;

ALTER TABLE photo MODIFY COLUMN title varchar(20);

ALTER TABLE photo MODIFY COLUMN directory varchar(20);

ALTER TABLE category_photo MODIFY COLUMN photo_id smallint(5) NOT NULL;

ALTER TABLE category_photo MODIFY COLUMN category_id tinyint(2) NOT NULL;

ALTER TABLE user MODIFY COLUMN id tinyint(2) not null AUTO_INCREMENT;

ALTER TABLE user MODIFY COLUMN version tinyint(2) NOT NULL;

ALTER TABLE user MODIFY COLUMN user_id varchar(12);

ALTER TABLE user MODIFY COLUMN password varchar(12);

ALTER TABLE user_category MODIFY COLUMN user_id tinyint(2) NOT NULL;

ALTER TABLE user_category MODIFY COLUMN category_id tinyint(2) NOT NULL;

quit