Portofino tutorial part 1: Installing and running the software

Posted by Paolo Predonzani
on March 10, 2009


In this tutorial I'll explain how you can install and run Portofino in approximately 15 minutes. For simplicity, we are going to use a popular choice of open source software (PostgreSQL, MySQL, Derby and Tomcat).

This tutorial is meant to be a gentle introduction. For more information, troubleshooting and to use Portofino on a broader range of commercial and open source databases and application servers, please see the official installation guide.

Java pre-requisites

As a pre-requisite, make sure you have a Java JRE or JDK installed. From the command line/shell type:

java -version

...and confirm that you have Java 1.5 or 1.6 installed. If needed, download the latest JRE or JDK from http://java.sun.com/javase/downloads/index.jsp.

Also, make sure that your Java installation can be found by applications that need it.
On MS Windows, from the command line, type:
set JRE_HOME=path_to_your_JRE_installation
or
set JAVA_HOME=path_to_your_JDK_installation

NOTE: even if there are spaces in your path_to_your_..._installation, don't surround it with quotes  ( " ).
E.g.
set JRE_HOME=C:\Program Files\java\jre6

On Linux and Mac OS X, from a bash shell, type:
export JRE_HOME=path_to_your_JRE_installation
or
export JAVA_HOME=path_to_your_JDK_installation

Option 1: the one-click-start Portofino

If you want to start using Portofino very quickly and you don't want the hassle of installing and managing a database and a Java application server, then the Portofino one-click installer is your best choice.

Download the one-click-start-portofino package (in .zip or .tar.gz fromat) and expand the archive. You should see a directory called "one-click-start-portofino-3.0". This is the whole installation - you can keep it on your desktop, in your home directory, or move it to a more stable location (the system's application folder) of your choice.

The start Portofino on Windows, from the command line type:
cd path_to_one-click-install-portofino-3.0\apache-tomcat-6.0.18
bin\startup.bat

On Linux and Mac OS X, from the shell type:
cd path_to_one-click-install-portofino-3.0/apache-tomcat-6.0.18
bin/start.sh

Finally go to this URL in your browser: http://127.0.0.1:8080/ and you should see Portofino's homepage. That's it. You now can start modeling your new application.

But there's more. If you connect to http://127.0.0.1:8080/tt you get a second instance of Portofino pre-loaded with the demo ticket-tracker application that you see in our main video.
Important: when you connect to the ticket-tracker you will be presented with a login screen. Use this login/password downstairs: paolo/paolo. And upstairs: admin/admin.
If you'd like to learn more about how the ticket-tracker application works, a useful tutorial is "Ticket Tracker - The data model".

As a technical note, the one-click-start package uses Apache Derby as an embedded database. While this is fine for a test/trial environment, I recommend that, for a production environment, you move to the installation described in option 2.

Option 2: installing the separate components

If you want more control over your installation, you can install the following components separately:
  • a relational database: PostgreSQL or MySQL
  • the JDBC driver for the database
  • a Java servlet container: Tomcat
  • Portofino
You may already have some software in this list on your computer or you may want to customize the installation process. You are free to do so.

An important notice: you only need one database - you if install PostgreSQL you don't need MySQL and vice-versa.

Installing PostgreSQL

At the time of writing the most recent version of PostgreSQL is 8.4, but any version since 8.1 will do. The official download page is here http://www.postgresql.org/download/.

On most Linux distributions PostgreSQL can be easily installed through the system's package manager (yum, apt-get, synaptic, etc).

On MS Windows and Mac OS X, a popular one-click installer is available from EnterpriseDB and includes several tools (including pgAdmin) in addition to the basic db server.

On Mac OS X, other popular options are to use Fink or MacPorts.

If it's not included in the database installation already, I recommend you also install a convenient administration tool called pgAdmin.

Installing MySQL

At the time of writing the most recent version of MySQL is 5.1. The official download for MS Windows, Linux, Mac OS X and many other platforms is here.

On most Linux distributions MySQL can be easily installed through the system's package manager (yum, apt-get, synaptic, etc).

Some MySQL installations come bundled with MySQLAdmin and other administration tools. If not, you can download the separate MySQL GUI Tools.

Installing Tomcat

You can download Tomcat here. There are several versions. We recommend Tomcat 6, but if you're more familiar with the older Tomcat 5.5, go with that. There are some differences between the two, which I'll highlight as we progress through the installation.
Install it (expand it) to any directory you like: we'll refer to that directory as $CATALINA_HOME.

On MS Windows, you should have items in the Start menu to start and stop Tomcat. Also, check the system tray for an icon with a similar purpose.

On all variants of *nix, you can start Tomcat from the shell:

export CATALINA_HOME=the_path_to_your_tomcat_installation
cd $CATALINA_HOME
bin/startup.sh

and similarly to stop it:

bin/shutdown.sh

If you encounter any problems while running Portofino, the first place to check is the log file located at CATALINA_HOME/logs/catalina.out.

Installing the JDBC driver

PostgreSQL's JDBC driver can be found here. Your safest choice is to download the JDBC3 driver (e.g., 8.3-604 JDBC 3), especially if you're using a Java 1.5 JRE/JDK.
The relevant file is postgresql-8.3-604.jdbc3.jar

MySQL's JDBC driver is called Connector J/5.1 and can be downloaded here.
After you've opened the archive, the relevant file is mysql-connector-java-5.1.7-bin.jar

Whichever database you choose, copy the driver to:
  • CATALINA_HOME/lib on Tomcat 6
  • CATALINA_HOME/common/lib on Tomcat 5.5
Downloading Portofino here. Look for the file called manydesigns-portofino-3.0-os-bin.zip (or tar.gz). Expand the archive. Its content should look like this:

|-- OPEN-SOURCE-LICENSE.txt
|-- THIRDPARTIES.txt
|-- portofino-war-3.0.war
`-- sql
     |-- mdtemplate-db2v9-3.0.sql
     |-- mdtemplate-derby10-3.0.sql
     |-- mdtemplate-mysql5-3.0.sql
     |-- mdtemplate-oracle9-3.0.sql
     |-- mdtemplate-postgresql8-3.0.sql
     `-- mdtemplate-sqlserver2005-3.0.sql

OPEN-SOURCE-LICENSE.txt contains the GPL with FLOSS exception license of Portofino.
THIRDPARTIES.txt contains the licenses for the libraries included in Portofino.

portofino-war-3.0.war is the war file we are going to deploy in Tomcat.

The sql directory contains the templates for various databases. These are only needed for manual database installations. We can safely ignore them here.

Creating the database on PostgreSQL

If you have pgAdmin, you can create and populate the database through the graphical user interface. I won't describe the clicks and actions you have to do but if you read the following discussion (which refers to shell/command line operations) you should easily find your way.

On Linux and Mac, start the psql client as the "postgres" user:

sudo -u postgres psql

On MS Windows start psql from the "SQL Shell (psql)" menu. Accept the default connection options and enter the password.

Then type:

CREATE USER username WITH PASSWORD 'password';
CREATE DATABASE portofinodb WITH OWNER='username' ENCODING='UTF8';

You can customize the database name, username and password of course.
The database is now ready.

Creating and populating the database on MySQL

If you have MySQL Administrator or other administration tools, you can create and populate the database through the graphical user interface. I won't describe the clicks and actions you have to do but if you read the following discussion (which refers to shell/command line operations) you should easily find your way.

From the shell/command line:

mysql -uroot -p

Then type:

SET CHARACTER SET 'UTF8';
SET sql_mode = 'ANSI';
CREATE DATABASE model CHARACTER SET "UTF8";
CREATE DATABASE meta CHARACTER SET "UTF8";

This actually creates two databases: one called "model" for data and another one called "meta" for metadata.
 
Then start MySQL client in interactive mode:

mysql -uroot -p

Create the application's user and grant it all privileges on the two databases:

grant all on model.* to username@localhost identified by 'password';
grant all on meta.* to username@localhost;
grant all on model.* to username@'%' identified by 'password';
grant all on meta.* to username@'%';

The database in now ready.

Configuring Portofino

Create a text file called portofino-custom.properties in the following directory:
  • CATALINA_HOME/lib on Tomcat 6
  • CATALINA_HOME/common/lib on Tomcat 5.5
Copy and paste the following content into it:
For PostgreSQL:

database.jdbc.driverClass=org.postgresql.Driver
database.jdbc.connectionURL=jdbc:postgresql://localhost:5432/portofinodb
database.jdbc.username=username
database.jdbc.password=password

For MySQL:

database.jdbc.driverClass=com.mysql.jdbc.Driver
database.jdbc.connectionURL=jdbc:mysql://localhost/model?characterEncoding=UTF-8&useUnicode=true&sessionVariables=sql_Mode=ANSI
database.jdbc.username=username
database.jdbc.password=password

An important notice: make sure that the connectionURL string is on one line and that all the parameters (from characterEncoding to sql_Mode=ANSI) are included.

Save the file and... this is it: this is the minimal configuration Portofino needs to start.

Deploying and finishing the installation Portofino

The installation guide describes four techniques to deploy an application on Tomcat. I won't repeat them here as the descriptions and the screenshots would take a lot of space. But I suggest you read that document and follow the section "Using the Tomcat Web Application Manager". The main points are:
  • make sure an admin user is defined in tomcat-users.xml,
  • start Tomcat and connect to the Tomcat web application manager,
  • choose a context path (e.g. /myapp )
  • enter the absolute path of the war file on your file system in "WAR or directory URL"
  • click on Deploy
After a few seconds the page should reload and your new Portofino instance should be listed under "Applications". Make sure its status is "running".
Click on its link (if you chose "/myapp" as the context path, the url should be http://127.0.0.1:8080/myapp).
An install/upgrade page will appear:

Click on "Proceed". Portofino will connect to the database and populate it with the basic data structures it needs.
At the end you'll see a page like this:



Click on the link. You're now ready to use Portofino.

In part 2 of this tutorial we'll create our first application from scratch.