Expresso Complete Installation Instructions

This document describes the installation process for the "Expresso Complete" bundle, which contains the files required to get Expresso up and running quickly.

Version:

Expresso 5.5

Maintainer:

Sandra Cann

Introduction

This document describes the installation process for the "Expresso Complete" bundle, which contains the files required to get Expresso up and running quickly, including a pre-configured version of the Jakarta Jakarta Tomcat 4.x web/servlet/JSP engine and Hypersonic database to get you up quickly. Tomcat 4.x is an implementation of the Java Servlet 2.3 and JSP 1.2 specifications.

You can change Tomcat or Hypersonic db once you are setup. Should you wish to do this deploy the complete version untouched and unchanged, and leave it alone in it's own separate folder, to go back and run it when you need to figure something out. This should not take more than 10 or 20 minutes. Then follow the instructions on site in the documentation for deploying on another app server or database. Get this running separately, again, without touching the complete version. Last but not least, find a buddy somewhere in the archives or from the list server who has deployed on your brand and version of the appServer, and get some tips. When you are successful, consider posting a little tutorial for your brand and version of app server, to leave bread crumbs for the next guy to follow; or better yet submit a documentation update to support@jcorporate.com.

Before starting with the instructions below please be sure to read the following:

System Requirements

Before starting, please review the System Requirements to ensure your system is able to run Expresso.
Download

The first step is to download Expresso's source code and supporting files. You should download the complete download for the below installation instructions. Expresso can be freely downloaded from here. Early access releases are also available to registered users.

Also available is a single .WAR (Web Application Archive) file, which contains the Source Code, Object code, required library .jar files, and the HTML/JSP files that make up Expresso in which case you would use these installation instructions. A new dev snapshot version is also available onsite each day; and the source for the .jar files included is available separately via the CVS archive, but is not normally required for using Expresso.
System Prerequisites

Before starting the install process, please review the System Pre-Requisites to ensure you are ready.

Installing on Unix/Linux/Solaris

Follow the steps below:

Choose a directory for the installation, creating it if required. We'll assume you've chosen /home/expresso for this example - substitute your directory name as required.
Locate your Java Development Kit installation. You must have at least JDK1.2. We'll assume it's in /home/jdk, again substitute as required.
Go to your /home/expresso directory and copy the expressoX-XX-complete.jar file into that directory. (X-XX is the version number of Expresso, such as 5-50).
Un-jar the file by issuing: /home/jdk/bin/jar xvf expressoX-XX-complete.jar. A number of files and directories will be created.
cd to the "bin" directory just created and issue a "chmod +x *" to make all of the scripts executable.
Issue a "set JAVA_HOME=/home/jdk" or other "set" command as required by your shell program to set the JAVA_HOME environment variable.
Type ./startup.sh
Tomcat should then start up, though depending upon how fast/slow the host machine is, this could take a little time. A good rule of thumb is when the file sizes in the logs directory stop changing the server is up.. Once Tomcat boots up you can then browse to the Expresso home page at: http://yourservername:8080/expresso/frame.jsp, where "yourservername" is the name of your server (or "localhost"). For example, it might be http://vaio:8080/expresso/frame.jsp. If you type in the url before Tomcat boots up properly it will not work.You can also see Tomcat's documentation and examples by going to http://yourservername/ in your browser.

Installing on Windows

Follow the steps below:

Choose a directory for the installation, creating it if required. We'll assume you've chosen c:\expresso for this example - substitute your directory name as required.
Locate your Java Development Kit installation. You must have at least JDK1.2. We'll assume it's in c:\jdk, again substitute as required, for example it might be d:\jdk1.3.1_01.
Copy the expressoX-XX-complete.zip file into your c:\expresso directory (X-XX is the version number of Expresso, such as 5.50).
Unzip the file by double click (it should open up in Winzip, which you can then use to expand the files). A number of files and directories will be created.
Open Windows Explorer, open directory just created c:expresso/bin
Edit file startup.bat. Insert two set commands
At the beginning of the file issue a "set JAVA_HOME=c:\j2sdk1.4.0" command (or wherever your SDK resides to set the JAVA_HOME environment variable) and issue a "set CATALINA_HOME:c\expresso" command.
Save startup.bat. Doubleclick startup.bat You migth get this nasty message telling you that there is no memory available in your environment:
If this is the case, select file startup.bat with a click on the left mouse button, then click the right mouse button to get the properties menu. Select properties. You'll get this:

On memory, change all values from "automatic" to the max. value available.
You'll get another startup file with the DOS-Prompt sign in front of it (file name is startup.sh).
The same action as described above is needed to get shutdown.bat up and running.

Now doubleclick on the new startup.sh file.
Tomcat should then start up, though depending upon how fast/slow the host machine is, this could take a little time. A good rule of thumb is when the file sizes in the logs directory stop changing the server is up.. Once Tomcat boots up you can then browse to the Expresso home page at:
http://yourservername:8080/expresso/frame.jsp, where "yourservername" is the name of your server (or "localhost"). For example, it might be http://vaio:8080/expresso/frame.jsp. If you type in the url before Tomcat boots up properly it will not work. You can also see Tomcat's documentation and examples by going to http://yourservername/ in your browser. If you're running expresso on your own machine and localhost doesn't work, try http://127.0.0.1:8080/expresso/frame.jsp instead.
For your convenience, you can copy your startup and shutdown files to your desktop by simply drag and dropping them from Windows Explorer to any point on your desktop. They will be there for subsequents starts/shutdowns of expresso.

Administrative Login Password

Now you have completed the installation. :) Now you are ready to Login and begin using Expresso.

Login as "Admin" and leave Password blank

Example Applications

To make it easier to get rolling with Expresso, there are some "Example" applications that are available with example documentation explaining how to access the demo applications and how to use them as a basis for developing your own applications with Expresso. You might begin with a sample application such as:

Weblog Example document and code (for 5.5)
Location Example document and code. (for 5.05)
Orange Trader Example Web Application and related article. (for 5.05)

Also under the Examples project there is also an effort comunity underway onsite to develop an Expresso J2EE Pet Shop example application. This example will illustrate Sun's Java BluePrints guidelines and patterns implemented using the Expresso Framework. This sample application wil shows how to use the capabilities of the J2EE 1.3 platform to develop flexible, scalable, cross-platform enterprise applications based on the Expresso Framework.

After working with Example applications, the next step will be to install other applications, such as eForum or begin development. Here are some references for beginning to develop your own application.

Conclusion

So what is the next step you might be asking? Expresso has some optional features that you may want to download the appropriate 3rd party jars to take advantage of those features.

Bouncycastle: The Bouncycastle jar file does not get distributed with Expresso right now due to export restrictions. Download the jar that contains the files called: jce-jdk13-123.jar which works in both JDK 1.3 and JDK 1.4 fine. The crypto is used by Expresso itself... So you'll need it in your WEB-INF/lib directory. The ant build file can get it for you.... just run the get-crypto target and it will automatically deposit the appropriate bouncy castle JCE provider in the lib module's WEB-INF/lib directory where the rest of the build system will pick it up.

There are no "post-install" steps to Expresso other than connecting to an alternate database or beginning development. If you get a bug that has you hung up, it will likely get fixed very quickly with the community collaboration in which case you will want to download the daily -dev download.

In closing here are some additional Reference Material resources:

Getting Started Users Guide: Some commonly asked questions about next steps including setting up Different Database and/or Servlet Engine, and an introduction to developing with Expresso.
How To Users Guide: An excellent reference when you are first starting with Expresso.
Expresso Developer's Guide: to provide the Java developer with the information needed to develop with the Expresso Web Application Development Framework/Component Library.
Model-View-Controller Architecture Explained by Sun: By applying you separate core data access functionality from the presentation and control logic that uses this functionality. Such separation allows multiple views to share the same enterprise data model, which makes supporting multiple clients easier to implement, test, and maintain.
Struts Users Guide: This project which is integrated into Expresso, encourages application architectures based on the Model-View-Controller (MVC) design paradigm, colloquially known as Model 2 in discussions on various servlet and JSP related mailing lists.
DBMaint: A Step-by-Step Example: You'll find this at the end of the DBMaint chapter. It provides an introduction to the directory structure as well as walks the user through a step-by-step example.
Best Practice with Expresso Framework with Struts
For Expresso tag library examples to demonstrate best practices please see dbmaint, Login and Registration jsps as examples.
Books: Hans Bergsten 'Java Server Programming' book or 'Professional JSP' published by Wrox.

Contributors

Contributors to this document include: Sandra Cann, Geeta Ramani, and Ruedi Anneler.

If you find any trouble spots with this document, or something you'd like to see clarified please contact the maintainer of this document.