Installation

Introduction

PhotoXChange is a standard J2EE web application. Configuration settings are required for both the web application itself, and for the application server.

Web application configuration

To configure the web application, the following configuration settings must be done:

Where	Parameter Name	Meaning	Default value
`WEB-INF/classes/ org.wamblee.photos.properties`	org.wamblee.photos.path	Full path name of the directory where photos are stored. This directory must be created beforehand.	A path that works on some developer's system but most likely not on yours.
	org.wamblee.photos.realm	The security domain used. This must match with the JNDI name specified in `WEB-INF/jboss-web.xml` and it must also correspond with a security domain configured in the application server.	PhotoXChange
	org.wamblee.photos.security.userprincipal	The classname of the principal class representing the user.	org.jboss.security.SimplePrincipal
	org.wamblee.photos.admingroup	The name of the administrator group.	administrators

Database Setup

The only currently supported database is MySQL.

MySQL Setup

The aim of the MySQL setup is to setup a database with the following properties:

The InnoDB storage engine is used
Transaction isolation level is repeatable read
A single user is created with all rights

Selecting the storage engine

First of all, MySQL must be configured to use the InnoDB storage engine for the photos database. This can be done in two ways:

Configuration setting; Edit the my.cnf configuration file (usually located in /etc on *nix systems and add the following lines to the [mysqld] section: default-table-type = INNODB
After this, restart mysql.
After creating the database tables: For every database table execute the command alter table TABLE_NAME engine = INNODB to change the storage engine for that table to INNODB.

Create the database

Now create a MySQL database

mysqladmin -u root -p create photoxchange

Where root is the user name of the administrator and photoxchange is the name of the database.

Create a user on the database by logging in as administrator

mysql -u root -p photoxchange

and creating a user that has access to the database

grant all on * to username identified by 'password';

This creates a user that can access the database from the same host the database is running on. If MySQL is running on a different machine than the application server, consult the MySQL manuals for information on how to configure access for that user.

Transactions

After creating the database check the transaction settings by logging on to the photoxchange database as administrator and executing the command

show variables

The value of the tx_isolation variable should be REPEATABLE-READ. If this not the case, set the transaction level globally for all databases by specifying

transaction-isolation = REPEATABLE-READ

In the [mysqld] section of the my.cnf file. It is also possible to set the transaction isolation level for one database only using

SET GLOBAL TRANSACTION ISOLATION LEVEL REPEATABLE READ

See the MySQL manuals for more details.

Creating the database schema

Populate the database by executing the sql scripts provided with the delivery on the database. On *nix systems:

mysql -u username -p photoxchange < setup.sql

After this, execute the command show table status; to check that the tables indeed use the InnoDB storage engine.

Populating the database

The photos application will perform the following initializations automatically at startup.

Initialization performed	When?
Initialization of users with one user 'erik' and one administrator 'admin', both having password 'abc123'.	When no users have been defined.
Initialization of authorization rules.	When no authorization rules exist.

Application Server Setup

For each supported application server, a separate section is provided.

JBoss 4

For JBoss, configuration amounts to configuring the datasource and the security domain, The name of the security domain must match that specified in configuration settings.

Datasource Setup

First of all, the database driver for MySQL must be installed by copying the driver jar mysql-connector-java-3.x.y-bin.jar from the MySQL web site to the server/default/lib directory of JBoss.

Next, the datasource must be configured by copying a photos-ds.xml file to the server/default/deploy directory of the application server and choosing the correct username and password.

Security Setup

To configure security, add the following security domain configuration to login-config.xml in the server/default/conf directory of the server:

guest

java:/PhotoXChange

SELECT PASSWORD FROM USERS WHERE NAME = ?;

select g.name, 'Roles' from USERS u, USER_GROUPS ug, GROUPS g where u.id = ug.user_id and ug.group_id = g.id and u.name = ?

MD5

hex

]]>

Note the module option dsJndiName which refers to the previously configured datasource. Also, note the module options hashEncoding and hashAlgorithm which specify that passwords should be stored as a base 16 MD5 hash.

Managing users and groups

This release of PhotoXChange provides a rudimentary user interface for managing users and groups. This interface can be accessed by logging in as administrator and clicking on 'Administration'.

Alternatively, users and groups may be modified using direct SQL. The table below shows some common scenarios

Scenario	Howto
Changing a password	`update USERS set password = md5('password') where user = 'username'`. The MD5 encoded password can also be generated using openssl: `echo -n PASSWORD \| openssl dgst -md5 -hex`
Adding a user	Add a new row to the USERS table and add a new row to the USER_GROUPS table to add the user to a group.
Adding a group	Add a new row to the GROUPS table.
Adding a user to a group	Add an entry to the USER_GROUPS table