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.
As a pre-requisite, make sure you have a Java JRE or JDK installed. From the command line/shell type:
...and confirm that you have Java 1.5 or 1.6 installed. If needed, download the latest JRE or JDK from http://www.oracle.com/technetwork/java/javase/downloads/index.html.
Also, make sure that your Java installation can be found by applications that need it.
On MS Windows, from the command line, type:
NOTE: even if there are spaces in your path_to_your_..._installation, don't surround it with quotes ( " ).
set JRE_HOME=C:\Program Files\java\jre6
On Linux and Mac OS X, from a bash shell, type:
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.1". 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.
To start Portofino on Windows, from the command line type:
On Linux and Mac OS X, from the shell type:
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
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 - if you install PostgreSQL you don't need MySQL and vice-versa.
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.
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.
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:
and similarly to stop it:
If you encounter any problems while running Portofino, the first place to check is the log file located at
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
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
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.1-os-bin.zip (or tar.gz). Expand the archive. Its content should look like this:
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.1.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.
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
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.
Create a text file called portofino-custom.properties in the following directory:
CATALINA_HOME/lib on Tomcat 6
CATALINA_HOME/common/libon Tomcat 5.5
Copy and paste the following content into it:
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.