Matte: Installation Guide

Matte is a personal photo, movie, and audio organization and publishing tool. It allows you to upload media items to your web server and then organize these items into albums, which you can then publish and share with friends and family. Matte is a web-based application which means you need an Internet-accessible server machine you can deploy it to (i.e. a hosting provider or your own personal server).

Requirements

Matte is a 100% Java web application that requires a relational database. Currently the requirements are as follows:

Java 5

Get the appropriate Java JDK/JRE for your server platform. You can get this from Sun, IBM, or Blackdown.

Database

Matte has been tested with both the 7.4 and 8.1 series of PostgreSQL. You can download PostgreSQL from postgresql.org.

Matte has also been tested with MySQL 4.1. You can download MySQL from mysql.com.

Note Matte can easily run in other databases. If you are familiar with Hibernate then you should be able to alter the Matte configuration to use any database system Hibernate supports.

Java servlet container
Matte is distributed as a Java web application (WAR). To use this you'll need a servlet container to deploy it into. Matte has been extensively tested with the Tomcat 5.5 server. Any J2EE servlet container should work, however.
Web browser
The main media organization UI has been tested and is known to work in the Firefox (1.5+) and Safari (2+) web browsers. When sharing albums, browser requirements depend on the theme being used. The default built-in Woosh theme is known to work in Firefox, Safari, and IE (6+).

Database setup

You must initialize your database for first-time use. Any modern relational database should work with Matte, but it has been tested only on PostgreSQL, MySQL, and Apache Derby. Instructions for PostgreSQL and MySQL follow.

Please note these are example database setup instructions, and you should adjust them to suit your own environment.

PostgreSQL

  1. Create a database user matte for Matte

    createuser -ADEP matte

    You will be prompted to enter the matte user's password. If you get a permissions error when you attempt to run this command, make sure you are executing it as a Postgres user with sufficient privileges. You can explicity run as the Postgres super-user with

    createuser -U postgres -ADEP matte

    in which you may be prompted for the postgres user's password.

  2. Create a matte database for Matte

    As a Postgres super-user, execute:

    createdb -E UNICODE -O matte matte

    Again, you may need to pass the -U flag to specify a Postgres super-user to execute the command as. The database must be created with the Unicode encoding (the -E UNICODE option does this).

  3. Create database tables

    Once the database user and database is created, you must create the tables necessary for Matte to run. These scripts must be executed as the database user you created previously (i.e. matte). Execute the table creation scripts like this:

    psql -U matte -d matte -f setup/sql/postgres/create-tables.sql psql -U matte -d matte -f setup/sql/postgres/create-system.sql

    Ignore any warnings about "table X does not exist".

MySQL

  1. Create a database user matte for Matte

    As a MySQL super-user mysql -u root mysql), execute:

    mysql> create database matte character set utf8; mysql> grant all privileges on matte.* to 'matte'@'localhost' identified by 'matte'; mysql> flush privileges;

  2. Create database tables

    Once the database user and database is created, you must create the tables necessary for Matte to run. These scripts must be executed as the database user you created previously (i.e. matte). Execute the table creation scripts like this:

    mysql -u matte -p matte -f <setup/sql/mysql/create-tables.sql mysql -u matte -p matte -f <setup/sql/mysql/create-system.sql

    Ignore any warnings about "Table 'X' doesn't exist".

Application server setup

Matte depends on a J2EE application server it is running in to provide a JDBC DataSource to connect to the database with and a JavaMail Session for sending mail with. Thus you must configure the DataSource and Session the first time you install Matte, and this configuration varies depending on the application server you are using.

Apache Tomcat 5.5+

For Tomcat 5.5 or later, create the DataSource first by creating a deployment context file named <TOMCAT HOME>/conf/Catalina/localhost/matte.xml. Add the below XML (adjust the parameter values as necessary for your environment, but if you are following these directions from the start, these should work for you).

Note that Tomcat does not ship with the JavaMail binaries, you must download both JavaMail and the required Java Activation Framework for for the javax.mail.Session support required by Matte. See the Tomcat JNDI Resources page (the JavaMail Sessions section) for more information and links to the associated download pages. Place the JARs in the <TOMCAT HOME>/common/lib directory.

PostgreSQL

Create the matte.xml deployment descriptor like shown here. Then, if you don't already have the Postgres JDBC driver added to Tomcat, copy the setup/lib/postgresql-8.1-407.jdbc3.jar that comes with Matte to the <TOMCAT HOME>/common/lib directory.

<Context path="/matte" className="org.apache.catalina.core.StandardContext" crossContext="false" reloadable="false" mapperClass="org.apache.catalina.core.StandardContextMapper" useNaming="true" debug="0" swallowOutput="false" privileged="false" displayName="Matte" wrapperClass="org.apache.catalina.core.StandardWrapper" docBase="/path/to/matte.war" cookies="true" cachingAllowed="true" charsetMapperClass="org.apache.catalina.util.CharsetMapper"> <Resource name="jdbc/matte" type="javax.sql.DataSource" scope="Shareable" driverClassName="org.postgresql.Driver" url="jdbc:postgresql://localhost:5432/matte" username="matte" password="matte" maxWait="5000" maxActive="4" maxIdle="2" removeAbandoned="true" removeAbandonedTimeout="60" logAbandoned="true" validationQuery="select CURRENT_TIMESTAMP" /> <Resource name="mail/matte" type="javax.mail.Session" scope="Shareable" mail.smtp.host="localhost" /> </Context>

MySQL

Create the matte.xml deployment descriptor like shown here. Then, if you don't already have the MySQL JDBC driver added to Tomcat, copy the setup/lib/mysql-connector-java-5.0.5-bin.jar that comes with Matte to the <TOMCAT HOME>/common/lib directory.

<Context path="/matte" className="org.apache.catalina.core.StandardContext" crossContext="false" reloadable="false" mapperClass="org.apache.catalina.core.StandardContextMapper" useNaming="true" debug="0" swallowOutput="false" privileged="false" displayName="Matte" wrapperClass="org.apache.catalina.core.StandardWrapper" docBase="/path/to/matte.war" cookies="true" cachingAllowed="true" charsetMapperClass="org.apache.catalina.util.CharsetMapper"> <Resource name="jdbc/matte" type="javax.sql.DataSource" scope="Shareable" driverClassName="com.mysql.jdbc.Driver" url="jdbc:mysql://localhost:3306/matte" username="matte" password="matte" maxWait="5000" maxActive="4" maxIdle="2" removeAbandoned="true" removeAbandonedTimeout="60" logAbandoned="true" /> <Resource name="mail/matte" type="javax.mail.Session" scope="Shareable" mail.smtp.host="localhost" /> </Context>

Matte WAR setup

To install Matte now, copy the WAR file included in the Matte binary package to your application server's deployment directory. For Tomcat this defaults to <TOMCAT HOME>/webapps.

You might want to adjust the application logging, which by default will attempt to log via Log4J to the console. You can adjust the verbosity and location of this log by unpacking the WAR and editing the <MATTE WAR>/WEB-INF/classes/log4j.properties Log4J configuration. Then either change your application server configuration to point to the unpacked WAR directory or zip up the unpacked WAR directory back to the original file name.

First-time use

Start up your application server. Once started, visit

http://<your server>:<port>/matte

where <your server> is the machine Matte is running on (e.g. localhost) and <port> is the port the applicaiton server is listening on. For Tomcat this would default to:

http://localhost:8080/matte

You should see the Matte Setup Wizard page. The Setup Wizard will guide you through configuring the remaining Matte options.

Matte Setup Wizard
The Matte Setup Wizard.
SourceForge.net Logo