About |  Getting started  |  Using |  Administration

About

Getting started

The image collection needs to be prepared as follows:-

On a Gnu/Linux system webnail will create the file structure and image reductions for you - otherwise this is likely to be pretty painful! Here's a tree view of a fictious photo collection as an example:- 

david@mapoko $ tree /home/PhotoAlbum/
/home/PhotoAlbum/
├── 2010
│   ├── back_to_school.jpg
│   ├── med
│   │   ├── back_to_school.jpg
│   │   ├── snow.jpg
│   │   ├── spring_flowers.jpg
│   │   └── swimming_pool.jpg
│   ├── snow.jpg
│   ├── spring_flowers.jpg
│   ├── swimming_pool.jpg
│   └── tn
│       ├── back_to_school.jpg
│       ├── snow.jpg
│       ├── spring_flowers.jpg
│       └── swimming_pool.jpg
├── 2011
│   ├── med
│   │   ├── new_school_year.jpg
│   │   ├── snow+ice.jpg
│   │   ├── spring_flowers.jpg
│   │   └── swimming_summer.jpg
│   ├── new_school_year.jpg
│   ├── snow+ice.jpg
│   ├── spring_flowers.jpg
│   ├── swimming_summer.jpg
│   └── tn
│       ├── new_school_year.jpg
│       ├── snow+ice.jpg
│       ├── spring_flowers.jpg
│       └── swimming_summer.jpg
├── Canaries
│   ├── beach.jpg
│   ├── med
│   │   ├── beach.jpg
│   │   ├── mountain_village.jpg
│   │   └── pansion.jpg
│   ├── mountain_village.jpg
│   ├── pansion.jpg
│   └── tn
│       ├── beach.jpg
│       ├── mountain_village.jpg
│       └── pansion.jpg
├── Georgina
│   ├── birthday.jpg
│   ├── med
│   │   ├── birthday.jpg
│   │   └── schoolUniform.jpg
│   ├── schoolUniform.jpg
│   └── tn
│       ├── birthday.jpg
│       └── schoolUniform.jpg
├── holiday
│   ├── airport.jpg
│   ├── beach.jpg
│   ├── med
│   │   ├── airport.jpg
│   │   ├── beach.jpg
│   │   └── train.jpg
│   ├── tn
│   │   ├── airport.jpg
│   │   ├── beach.jpg
│   │   └── train.jpg
│   └── train.jpg
├── house&garden
│   ├── darling_wife.jpg
│   ├── fruit_trees.jpg
│   ├── med
│   │   ├── darling_wife.jpg
│   │   ├── fruit_trees.jpg
│   │   └── viewKitchen.jpg
│   ├── tn
│   │   ├── darling_wife.jpg
│   │   ├── fruit_trees.jpg
│   │   └── viewKitchen.jpg
│   └── viewKitchen.jpg
├── Laurenzo
│   ├── birthdayBoy.jpg
│   ├── med
│   │   └── birthdayBoy.jpg
│   └── tn
│       └── birthdayBoy.jpg
├── Louise
│   ├── med
│   │   ├── prom.jpg
│   │   └── tennis.jpg
│   ├── prom.jpg
│   ├── tennis.jpg
│   └── tn
│       ├── prom.jpg
│       └── tennis.jpg
├── Swallows
│   ├── feathers.jpg
│   ├── med
│   │   ├── feathers.jpg
│   │   └── wings.jpg
│   ├── tn
│   │   ├── feathers.jpg
│   │   └── wings.jpg
│   └── wings.jpg
└── xmas
    ├── med
    │   └── yuleLog.jpg
    ├── tn
    │   └── yuleLog.jpg
    └── yuleLog.jpg

30 directories, 75 files

From here though it's easy; you just need a java runtime environment with an app server such as tomcat. Download the PhotoAlbum.war file and copy it to the appropriate directory (webapps on tomcat)

Tomcat unpacks the war archive to webapps/PhotoAlbum. You can copy the prepared collection to webapps/PhotoAlbum/Album, but a better plan on tomcat7 is to configure it to use /Album as an alias. In conf/context.xml you need something like:- 

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

Lastly, before restarting tomcat to pick up this config change, edit the default config file that has been created in the base of the tomcat install at .photoalbum/photoalbum. Make the file look something like this:- 

#the filename extension - one of jpg, JPG, jpeg, JPEG
jpg
#the database -one of hsqldb, mysql, postgres
hsqldb
#full real path to your photoalbum directory, with trailing path separator
/home/PhotoAlbum/

The 2nd line should be changed if your collection does not use the jpg extension; for now at least leave the 4th line unchanged and enter the full path to the photos - either PATH_TO_TOMCAT/webapps/PhotoAlbum/Album/ or to the actual photo files if you are using an alias. Do not delete the comment lines.

Assuming you're testing on your desktop machine, you can now browse to http://localhost:8080/PhotoAlbum and login as admin with password password

Using

PhotoAlbum administrator
users |  categories  |  adding photos 1 |  editing photos |  adding photos 2 |  databases |  logs

managing users
  • if you run this on a public facing server you must change access details, select Administration then admin from the User List. The login name does not have to remain as admin
  • you can also add, delete and edit other user accounts
  • the admin user automatically gets access to all categories and the guest user has the public category
  • 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

    adding individual photos

    editing photos

    adding photos the fast way

    database management

    This section is for reference; although you may decide to make some of these changes or carry out some of these operations, it's largely a matter of preference rather than necessity.

    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 simultaneous views or you already have mysql running on your server, you may want to switch. If you already built up a sizable database the export / import facility will be your friend.

    You can prepare mysql by entering the commands below:-

    mysql -u root -p;  
create database PhotoAlbum_prod;
grant all on PhotoAlbum_prod.* to 'photoalbum'@'localhost' identified by '';
flush privileges;

    You'll need your mysql root password for the first command, the database name is case sensitive and the the photoalbum user must be created with an empty password. 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 (utilities directory) from the OS command line with 

    mysql -u photoalbum PhotoAlbum_prod < PhotoAlbum_mysql

    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:-

    david@mapoko $ mysql --u photoalbum

mysql>use PhotoAlbum_prod
mysql>ALTER TABLE category MODIFY COLUMN id tinyint(2) AUTO_INCREMENT;
mysql>ALTER TABLE category MODIFY COLUMN version smallint(5) NOT NULL;
mysql>ALTER TABLE category MODIFY COLUMN title varchar(20);

mysql>ALTER TABLE photo MODIFY COLUMN id smallint(5) AUTO_INCREMENT;
mysql>ALTER TABLE photo MODIFY COLUMN version tinyint(2) NOT NULL;
mysql>ALTER TABLE photo MODIFY COLUMN title varchar(20);
mysql>ALTER TABLE photo MODIFY COLUMN directory varchar(20);

mysql>ALTER TABLE category_photo MODIFY COLUMN photo_id smallint(5) NOT NULL;
mysql>ALTER TABLE category_photo MODIFY COLUMN category_id tinyint(2) NOT NULL;
mysql>ALTER TABLE user MODIFY COLUMN id tinyint(2) not null AUTO_INCREMENT;
mysql>ALTER TABLE user MODIFY COLUMN version tinyint(2) NOT NULL;
mysql>ALTER TABLE user MODIFY COLUMN user_id varchar(12);
mysql>ALTER TABLE user MODIFY COLUMN password varchar(12);

mysql>ALTER TABLE user_category MODIFY COLUMN user_id tinyint(2) NOT NULL;
mysql>ALTER TABLE user_category MODIFY COLUMN category_id tinyint(2) NOT NULL;
mysql>quit

    switching to postgresql

    Download a postgresql JDBC driver and put it in the PhotoAlbum/WEB-INF/lib or tomcat/lib directory.

    The default authentication policy allows system users to access databases with their system passwords, whereas we need a non system user to authenticate. Make the pg_hba.conf file look like this (password authentication):- 

    # TYPE  DATABASE        USER            ADDRESS          METHOD

# "local" is for Unix domain socket connections only
local   all             all                              password
# IPv4 local connections:
host    all             all             127.0.0.1/32     password
# IPv6 local connections:
host    all             all             ::1/128          password

    and restart postgresql.

    As the postgres user, create the user photoalbum with password photoalbum:-

    postgres@mapoko:/home/david$ createuser -P photoalbum
Enter password for new role:
Enter it again: 
Shall the new role be a superuser? (y/n) n
Shall the new role be allowed to create databases? (y/n) y
Shall the new role be allowed to create more new roles? (y/n) n

    Then create the database and to avoid having oversized tables, insert the empty one from the utilities directory:-

    postgres@mapoko:/home/david$  createdb -O photoalbum "PhotoAlbum_prod"
postgres@mapoko:/home/david$ psql -d "PhotoAlbum_prod" -U photoalbum < PhotoAlbum_postgres
Password for user photoalbum:
    and authenticate with the password photoalbum

    converting an existing database

    In addition to exporting an existing hsqldb / mysql database and importing into postgres, the mysql2pgsql.perl program seems to reliably convert a mysql database, which can then be inserted in the same way as an empty database (above).

    logs

    PhotoAlbum writes information to rotated log files in the .photoalbum directory. If the app is running a public network, it makes sense to keep on these for failed logins and also to see how it's being used. I suggest logwitch for help with this. Particular words to look for are FAILED (although someone may have typoed a password) and TERMINATED, which definitely indicates a user attempting to breakn access controls.