Install Planets Server and Planets Suite on a Linux server

Audience

This documentation is intended for developers who wish to install Planets Server and Planets Suite on a Linux server without using the GUI installer.
These guidelines can also be used for installation on a Linux Desktop and might also be applicable for Apple Macintosh environments, though this is not tested.

Prerequisites

- Linux server (e.g. Ubuntu Server)
- shell access
- root privileges (sudo) might come in handy if software is missing such as SVN
- in this guide the root-location of files and directory is /home/planets, you might need to substitute this accordingly if your homedirectory is not /home/planets
- in this guide you need to substitute [FILENAME] or [VERSION] with the appropriate filename or version

Preparing for installation

Install Java JDK

Planets Server and Suite are Java applications. In order to run them, installation of Java JDK (Development Kit) is required.
Download and install Java JDK 6: http://www.oracle.com/technetwork/java/javase/downloads/index.html

NOTE:  the official PDF documentation advises to use JDK 5, but you need Java JDK 6, otherwise some parts will not compile.

Install Apache ANT

The installation process of Planets Server and Suite requires Apache ANT, a tool to build Java applications.
Download and install ANT: http://ant.apache.org/
Install using apt: sudo apt-get install ant ant-optional

Adding PATHS, JAVA_HOME and ANT_HOME

After installation of Java JDK and ANT you need to add the installation directories of Java JDK and ANT to the $PATH environment-variable.
You also need to add $JAVA_HOME and $ANT_HOME to your environment.

Add the following lines to a new file in /etc/profile.d (recommended) or add it to .bashrc or appropriate shell login script.

export JAVA_HOME=/home/planets/jdk/jdk[VERSION]
export ANT_HOME=/home/planets/ant/apache-ant-[VERSION]
export PATH=${PATH}:${JAVA_HOME}/bin:${ANT_HOME}/bin

Don't forget to test the path and environment-variables by logging out and in again and echoing the variables, e.g. echo $PATH.

Downloading Planets Server and Planets Suite

In order to checkout (download) the Planets Server and Planets Suite you need a SVN tool such as Subversion.
Download and install Subversion: http://subversion.apache.org/
Install using apt: sudo apt-get install subversion

Checkout the Planets Server sourcecode:

svn co https://planets-server.svn.sourceforge.net/svnroot/planets-server/trunk ~/planets-server

Checkout the Planets Suite sourcecode:

svn co https://planets-suite.svn.sourceforge.net/svnroot/planets-suite/trunk ~/planets-suite

NOTE: You don't have to create the checkout directories yourself, the SVN tool will do this for you. In this example the directories are created in the home directory of the current user (~).

Installing Planets Server

Before installing Planets Server you have to change some variables that apply to your environment.
Change to the checkout directory of Planets Server (planets-server) and copy the file planets-server.properties.template to planets-server.properties.
You are advised to keep the .template file intact to serve as backup.

Open the file planets-server.properties with a text-editor and change the following variables. Comments are preceded by a #-sign.

Directory where the Planets Server should be installed

planets-server.root=/home/planets/planets-server-compiled

Directory where the Planets Server configuration should be stored

planets-server.config.dir=/home/planets/planets-server-compiled/server/default/conf/planets

Hostname of the Planets Server

planets-server.host=planets.local.lan

HTTP-port of the Planets Server

planets-server.port=8080

HTTPS-port of the Planets Server

planets-server.ssl.port=8443

Username and password of the DerbyDB database which will be created during installation

planets-server.db.useradmin.user=PlanetsDBAdmin
planets-server.db.useradmin.pw=changeMe

Email configuration settings and options

# required
planets-server.mail.host=mailserver.local.lan
# required (true/false)
planets-server.mail.auth=false 
# only required when mail.auth=true
planets-server.mail.user= 
# only required when mail.auth=true
planets-server.mail.password= 
# required (true/false)
planets-server.mail.debug=true 
# required
[email protected]
# required (true/false)
planets-server.mail.use.tls=false

Now we need to change some variables of the Planets Suite.
Change to the checkout directory of Planets Suite (planets-suite) and copy the file build.properties.template to build.properties.
Again, you are advised to keep the .template file intact to serve as backup.

Open the file build.properties with a text-editor and change the following variables. Comments are preceded by a #-sign.

*Directory where the Planets Server is installed (same as planets.server.root in planets-server.properties)*

if_server.dir=/home/planets/planets-server-compiled

Directory where the Planets Server configuration is stored (same as planets-server.config.dir in planets-server.properties)

if_server.conf=/home/planets/planets-server-compiled/server/default/conf/planets

Directory that stores the Data Registry configuration

if_server.doms.config.dir=/home/planets/planets-server-compiled/server/default/data/planets/dom-config

Hostname and ports of the Planets Server (same as configured in planets-server.properties)

if_server.host=planets.local.lan
if_server.port=8080
if_server.ssl.port=8443

Now we are ready to compile the Planets Server and Planets Suite.

Change to the checkout directory of Planets Server and issue the following commands

Deploy Planets Server

ant deploy:planets-server

This should complete with the message "BUILD SUCCESSFUL"

Create DerbyDB Database

ant create:dbs

This should complete with the message "BUILD SUCCESSFUL". Note that some SQL-commands will fail, this is normal.

Now change to the checkout directory of Planets Suite and issue the following commands:

Deloy Framework

ant deploy:framework

This should complete with the message "BUILD SUCCESSFUL"

Deploy Services

ant deploy:services

This should complete with the message "BUILD SUCCESSFUL"

Deploy Testbed

ant deploy:testbed

This should complete with the message "BUILD SUCCESSFUL"

If any of the issued commands should complete with a message that the build has failed, please check the configuration settings.

Running Planets Server

Change to the bin directory where Planets Server and Planets Suite are installed.

cd /home/planets/planets-server-compiled/bin

Start the server with the following command:

./run.sh