Yttrium Links
Quick Links
Project Documentation
The Yttrium web application is quite easy to set up owing to the Maven project management and comprehension tool.
Follow these steps to build and deploy the application:
DOWNLOAD AND SET UP THE BASIC FRAMEWORKS
First download the following kits, tools and applications. It is possible allow all of them to be open source, by the way.
Download Java 2 Platform Standard Edition 5.0, from Sun Microsystems, Inc.. JDK 5.0 Update 6 will do fine. For information on the installation of the kit see the install guidelines.
Note that the JDK 5.0 is often called 1.5. Here is Sun's explanation. :-(
TODO: link in 1.5.0 and 5.0 commented out paragraph.
Download and install a server implementing the Servlet 2.4 and JSP 2.0 specifications. I would advise you to use Tomcat 5.5.13 since the application is set up to use this web server. The Jetty web server could also be used.
TODO: Include a list of web servers and explain the ease of the Maven plugins with these plugins (especially hot Jetty work).
A full list of open source servers implementing these specifications can be found here.
Download and install a relational database server. It is advised to use MySQL 4 since the Yttrium is configured for such a database after download.
It is however easy to use other databases since Hibernate, used in the persistence layer, supports many dialects.
Download the source code from the Yttrium site or get the latest greatest (sic) from the Subversion repository.
Maven is a software project management and comprehension tool. Based on the concept of a project object model (POM), Maven will manage Yttrium's build, reporting and documentation.
Download Maven 2 from the Apache site. It is advisable that you would read up on Maven on their site. Yttrium's own pom.xml will give you some hands-on help.
Some guidelines on the maven tool could be helpfull.
DATABASE SETUP
An application is most of the time quite useless if no data is persisted.
As in most web based applications, it is required that these data are saved in the Unicode character set [to show even Klingon if needs be ;-)] and that these data can be handled in a transaction aware environment.
The database needs to be configured to hold the Unicode character set using the UTF-8 encoding. This is possible with most common databases.
The database also must be able to have transaction-safe tables. In most databases this needs to be specified.
Here you can find some help on the MySQL database.
I created a simple sql script (for MySQL now, script for other database engines will follow soon.
To create the database schema, you can use this Maven command:
user@host:~/path/yttrium$ mvn initialize -Ddatabase=schema
After that the tables will be created. These tables will be empty however, so the application will not work (for example the database driven menu tags will throw exception messages when you would try to login).
To populate the application with test data, this Maven command will help:
user@host:~/path/yttrium$ mvn initialize -Ddatabase=populate
For now this is just a quick and (indeed) dirty hack to get the application running quickly. Soon a better mechanism (using hibernate3 plugin to autogenerate the tables automagically on many databases) will be in place.
WEBSERVER SETUP
The Tomcat guidelines show how to enable the https scheme. This scheme must be enabled to allow proper working of the Yttrium module.
PROPERTIES
A set of specific properties needs to be set up to allow access to your database, to your web servers an other yokemebobs.
Create (or update) a settings.xml file in your local repository. The local repository lives on your own ~/.m2 directory if you use a Linux box. I believe that on a Windows machine, the file is located at %userpath%/.m2/. Am i right?
You can use the settings.xml example below; do not forget to replace all the square bracketed [messages] with proper values. For example replace [your database username] by root or scott.
<settings>
<profiles>
<profile>
<id>yttrium-profile</id>
<properties>
<database-root-username>[yuor database root username]</database-root-username>
<database-root-password>[your database root password]</database-root-password>
<database-username>[your database yttrium username]</database-username>
<database-password>[your database password]</database-password>
<sourceforge-username>[your sourceforge username]</sourceforge-username>
<sourceforge-password>[your sourceforge password]</sourceforge-password>
<maven.docs.outputencoding>UTF-8</maven.docs.outputencoding>
</properties>
<!--
These need to be set to retrieve the tomcat mojo plugins
Without them it is impossible to redeploy Yttrium with tomcat
using Maven.
-->
<repositories>
<repository>
<id>Maven Snapshots</id>
<url>http://snapshots.maven.codehaus.org/maven2/</url>
<snapshots>
<enabled>true</enabled>
</snapshots>
<releases>
<enabled>true</enabled>
</releases>
</repository>
</repositories>
<pluginRepositories>
<pluginRepository>
<id>Maven Snapshots</id>
<url>http://snapshots.maven.codehaus.org/maven2/</url>
<snapshots>
<enabled>true</enabled>
</snapshots>
<releases>
<enabled>true</enabled>
</releases>
</pluginRepository>
<pluginRepositories>
</profile>
</profiles>
<!--
The admin and password to be used when using the
maven tomcat plugin
-->
<servers>
<server>
<id>tomcat-server</id>
<username>[your tomcat username with admin role]</username>
<password>[your password]</password>
</server>
</servers>
<activeProfiles>
<activeProfile>yttrium-profile</activeProfile>
</activeProfiles>
</settings> Several database-access properties are required to be set. It is possible to place them in the settings.xml file, I feel it is better to place them in the profiles.xml file. That way you could sepecify several databases. Here is an example for the mysql database
<profile>
<id>database</id>
<properties>
<database-type>mysql</database-type>
<database-host>localhost</database-host>
<database-port>3306</database-port>
<database-dialect>org.hibernate.dialect.MySQLInnoDBDialect</database-dialect>
<database-driver>com.mysql.jdbc.Driver</database-driver>
<database-name>yttrium</database-name>
<database-properties>
<![CDATA[
AutoReconnect=true&useUnicode=true&characterEncoding=UTF-8&useServerPrepStmts=false
]]>
</database-properties>
<database-showsql>true</database-showsql>
<database-url>
<![CDATA[
jdbc:mysql://localhost:3306/yttrium?AutoReconnect=true&useUnicode=true&characterEncoding=UTF-8&useServerPrepStmts=false
]]>
</database-url>
</properties>
</profile>TODO: Soon more properties will be specified here.
TODO: security.properties (JAAS + JDBC)
TODO: log.properties
TODO: database.properties
BUILD AND DEPLOY
Maven must be used to build and deploy Yttrium.
To see the current properties, use:
user@host:~/path/yttrium$ mvn help:effective-settings
You should see the usernames and passwords specified in your settings.xml file. Also you should see links to the snapshot repository which are required to retrieve the tomcat mojo plugin.
To build the WAR containing the full Yttrium web application, just type:
user@host:~/path/yttrium$ mvn package
You could use an archiving tool (like winzip or File Roller) to check the contents of the file.
It is best to see if the plugin is found in the Maven snapshot repository. More information can be found at the tomcat-maven-plugin site.
To see if the plugin is successfully retrieved and is running well, type:
user@host:~/path/yttrium$ mvn tomcat:info
One would expect something like:
[...] [INFO] [tomcat:info] [INFO] Listing server information at http://localhost:8080/manager [INFO] OK - Server info [INFO] Tomcat Version: Apache Tomcat/5.5.13 [INFO] OS Name: Linux [INFO] OS Version: 2.6.12-10-686 [INFO] OS Architecture: i386 [INFO] JVM Version: 1.5.0_06-b05 [INFO] JVM Vendor: Sun Microsystems Inc. [...]
It might happen that Maven complains. Please check:
If all is well, you can deploy the generated WAR; type:
user@host:~/path/yttrium$ mvn tomcat:deploy
Re-deployment happens through:
user@host:~/path/yttrium$ mvn tomcat:redeploy
TODO: Add in the mvn site explanation. (The reports! The reports! Save the reports!)
TODO: Add in the mvn site:deploy explanation.