This chapter will teach you to install the Plandora. The Plandora is a web tool, client-server and for this reason, it demands a little more complex configuration, but should not be a big deal.
First of all, you should have two things: a web server and a data base. In developing time, the Plandora uses the Tomcat and MySQL respectively, but you can host the Plandora into another web server (Servlet compatible). Bering in mind that you can choose another web server but you may find some initial difficulty, specially in data source configuration because this 'setup package' contains only the configuration for Tomcat. Nevertheless, feel free to choose another data base but remember that Plandora was tested only in MySQL.
This release package contains:
- plandora-vX.X.X.zip:
This zip file might contains:
- pandora.war: which will be used to 'publish' the tool into web server.
- MYSQL.sql: DON'T USE THIS SCRIPT if you have a previous Plandora! This file contains the SQL script for creation of table and some basic data. You should use this script only for a NEW installation.
- server.xml or context.xml: This file should be used for data source configuration purposes of Plandora into Tomcat
- release_notes.txt: The release notes file about the current version
... and one of those files:
- READ-ME_FOR_MIGRATION_FROM_v160: If you are updating your Plandora version from version 1.6.0, read this file to learn how to migrate to version 1.7.0 preserving the current data.
- READ-ME_FOR_MIGRATION_FROM_v130: If you are updating your Plandora version from version 1.3.0, read this file to learn how to migrate to version 1.6.0 preserving the current data.
- READ-ME_FOR_MIGRATION_FROM_v110: If you are updating your Plandora version from version 1.1.0, read this file to learn how to migrate to version 1.2.0 preserving the current data.
- READ-ME_FOR_MIGRATION_FROM_v100: If you are updating your Plandora version from version 1.0.0, read this file to learn how to migrate to version 1.1.0 preserving the current data.
- READ-ME_FOR_MIGRATION_FROM_v091: If you are updating your Plandora version from version 0.9.1, read this file to learn how to migrate to version 1.0.0 preserving the current data.
- update.sql: If you are updating your Plandora version from version 0.8.9, use this script instead MySQL.sql. Your current data will be preserved.
- plandoraInterface.jar: Since version 1.2.0, the installation package also includes this file, that can be used by developers in order to extend Plandora features or to customize specific points of system (ex.: notificator, knowledge base, project occurrence, etc)
- plandora-source-X.X.X:
The source files of tool
- READ_ME_XXX.txt
FIRST STEP: Getting the Tomcat and MySQL
Both tools are open source and for this reason, it can be downloaded from Internet freely and used without any cost. These tools are strongly consolidated and are of stable implementation.
We recommend using the version 5.0.28 for Tomcat and 4.1 for MySQL. These versions were stressed and successfully used during the tests.
The link to perform the Tomcat download is the Jakarta web site (community that is part of Apache Group, which implements and controls the Tomcat besides of many others interesting tools):
http://archive.apache.org/dist/jakarta/tomcat-5/
The link to perform the MySQL download of MySQL is the MySQL website: http://dev.mysql.com/downloads/
After downloading, you should install everything into the machine that will be the Plandora server. You can install the Data Base and Web Server in the same machine or separately. This decision should be based on your needs. Feel free.
For Windows installation, the Tomcat is a simple Zip file. To perform the installation, unzip the file into your machine file system.
For Windows MySQL, there is a Setup application, which after execution, requires some information as: data base user and password and data base type (choose the 'WebApplication' type)
Obs.: After the Windows installation, the MySQL will be installed as a Windows Service. This feature makes startup, shutdown, managing, logs, etc, easier.
SECOND STEP: Running the data base script
You should open the 'client screen' of MySQL. If you have used the Windows installation, this 'client screen' is accessible through 'Start' button ('MySQL Command Line Client'). After open it, the 'client screen' will ask a database password. You should enter the same password that you have created previously. Then, the data base will display a prompt ("mysql>").
Then, type: create database plandora;
And you might receive the response: Query OK, 1 row affected (0.01 sec)
With this command, you've just created a new 'database' object, and it is ready for data insertion.
Then, type: use plandora;
And you might receive the response: Database changed
This line means that you are saying to data base that everything that you will do from now on, will be done over the database called 'plandora' which was created previously.
In order to complete the process you should create the Plandora tables and insert some basic data but, bare in mind that if you are updating the version of Plandora DON'T USE THE 'MYSQL.sql' script. You must use the apropriate script to perform the migration the version and preserve the current data. In other hand, if you are performing a new installation, use the 'MYSQL.sql' script unziping the file 'Plandora-vX.X.X.zip' to a known place and typing this command into MySQL client: source [path_where_you_unziped]/mysql.sql;
Wait until all data population is done. After that, close the client screen through the command: quit
THIRD STEP: Starting the Tomcat
Copy the file mysql-connector-java-5.1.10-bin to folder common/lib/ of Tomcat. This is the library for MySQL data base access used by Tomcat. This lib is called ConnectorJ and could be dowloaded at http://dev.mysql.com/downloads/connector/j/5.1.html
The next step is to setup the Data Source. Tomcat will need this information for connection purposes and to supply a connection to the application. Actually the Tomcat takes the control of the data base 'connection pool'.
For Tomcat 5.0.x you should copy the server.xml (that comes with the installation package) to the folder conf/ of Tomcat.
For Tomcat 5.3.x or higher you SHOULD NOT copy the server.xml but you should edit the context.xml (get the example file that comes with the installation package 1.1.0) file into the folder conf/ of Tomcat.
Note: In both cases, it is necessary to change the fields user and password to the appropriate user settings that you have created during the Data Base installation.
After unzip the file 'plandora-vX.X.X.zip', the file 'pandora.war' will be created. Copy to folter /webapps of Tomcat. After that, start the Tomcat through 'startup.bat' (windows) or './startup.sh' (Linux) that is placed into Tomcat bin/ folder. After some seconds (and many screen messages), the message bellow should popup on the Tomcat console: 'INFO: Server startup in xxxx ms'. When this message popup, means that Tomcat is already started up and your machine is now a Web Server.
In order to test, open a browser and type into 'Location Bar': "http://localhost:8080". Notice that, we excluded the fragment 'www' because we are accessing locally. If a standard web site of Tomcat popup, it's working!
LAST STEP: Starting the Plandora
If everything is working with Tomcat, it should have been exploded the file pandora.war (that you have been put into /webapps folder) in a 'pandora' folder into the /webapps. This compartment is called 'application deploy'. Make sure that the Plandora deploy happened, and then, open a browser and type:
http://localhost:8080/pandora/do/login?operation=prepareLogin
It should display the login form of Plandora. Use the user 'root' without password to create new users and projects.
There are some users for testing. All of them have no password. You can remove or change if you want. Remember that, upon now (until you shutdown your Tomcat ;-) ) your machine is a web server that can be accessed for other machines in your network (or even by internet depending on your network settings) through the IP number or the machine name.
To do this, type the address below in another machine (client machine) in order to access Plandora:
http://[name_of_plandora_server]:8080/pandora/do/login?operation=prepareLogin
Have a nice projects!
