h3. 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.
h3. Prerequisites
{color:black}\- Linux server (e.g. Ubuntu Server){color}
{color:black}\- shell access{color}
{color:black}\- root privileges (sudo) might come in handy if software is missing such as SVN{color}
{color:black}\- in this guide the root-location of files and directory is /home/planets, you might need to substitute this accordingly{color} if your homedirectory is not /home/planets
{color:black}\- in this guide you need to substitute \[planetssuite:FILENAME\] or \[planetssuite:VERSION\] with the appropriate filename or version{color}
h3. Preparing for installation
h4. 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]
{quote}
{color:#ff0000}{*}NOTE: the official PDF documentation advises to use JDK 5, but you need Java JDK 6, otherwise some parts will not compile.*{color}
{quote}
h4. 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/|http://ant.apache.org/bindownload.cgi]
Install using apt: sudo apt-get install ant ant-optional
h4. 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.
{noformat}
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
{noformat}
Don't forget to test the path and environment-variables by logging out and in again and echoing the variables, e.g. *echo $PATH*.
h4. 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:
{noformat}
svn co https://planets-server.svn.sourceforge.net/svnroot/planets-server/trunk ~/planets-server
{noformat}
Checkout the Planets Suite sourcecode:
{noformat}
svn co https://planets-suite.svn.sourceforge.net/svnroot/planets-suite/trunk ~/planets-suite
{noformat}
_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 (~)._
h3. 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*
{code}
planets-server.root=/home/planets/planets-server-compiled
{code}
*Directory where the Planets Server configuration should be stored*
{code}
planets-server.config.dir=/home/planets/planets-server-compiled/server/default/conf/planets
{code}
*Hostname of the Planets Server*
{code}
planets-server.host=planets.local.lan
{code}
*HTTP-port of the Planets Server*
{code}
planets-server.port=8080
{code}
*HTTPS-port of the Planets Server*
{code}
planets-server.ssl.port=8443
{code}
*Username and password of the DerbyDB database which will be created during installation*
{code}
planets-server.db.useradmin.user=PlanetsDBAdmin
planets-server.db.useradmin.pw=changeMe
{code}
*Email configuration settings and options*
{code}
# 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
{code}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)\*
{code}
if_server.dir=/home/planets/planets-server-compiled
{code}
*Directory where the Planets Server configuration is stored (same as planets-server.config.dir in planets-server.properties)*
{code}
if_server.conf=/home/planets/planets-server-compiled/server/default/conf/planets
{code}
*Directory that stores the Data Registry configuration*
{code}
if_server.doms.config.dir=/home/planets/planets-server-compiled/server/default/data/planets/dom-config
{code}
*Hostname and ports of the Planets Server (same as configured in planets-server.properties)*
{code}
if_server.host=planets.local.lan
if_server.port=8080
if_server.ssl.port=8443
{code}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*
{code}
ant deploy:planets-server
{code}
This should complete with the message "BUILD SUCCESSFUL"
*Create DerbyDB Database*
{code}
ant create:dbs
{code}
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:
*Deploy Framework*
{code}
ant deploy:framework
{code}
This should complete with the message "BUILD SUCCESSFUL"
*Deploy Services*
{code}
ant deploy:services
{code}
This should complete with the message "BUILD SUCCESSFUL"
*Deploy Testbed*
{code}
ant deploy:testbed
{code}
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.
h3. Running Planets Server
Change to the bin directory where Planets Server and Planets Suite are installed.
{code}
cd /home/planets/planets-server-compiled/bin
{code}
Start the server with the following command:
{code}
./run.sh -b0.0.0.0
{code}"-b0.0.0.0" is to have the server broadcast on all available network adapters, otherwise it will only broadcast on 127.0.0.1 (localhost). You can also replace 0.0.0.0 with a specific IP-address.
Alternatively start the server with the following command to detach the process from the current terminal:
{code}
nohup ./run.sh -b0.0.0.0 &
{code}
Note: all output will be written to 'nohup.out'.
Further reading: [PT:Configure Planets Server storage folder]
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.
h3. Prerequisites
{color:black}\- Linux server (e.g. Ubuntu Server){color}
{color:black}\- shell access{color}
{color:black}\- root privileges (sudo) might come in handy if software is missing such as SVN{color}
{color:black}\- in this guide the root-location of files and directory is /home/planets, you might need to substitute this accordingly{color} if your homedirectory is not /home/planets
{color:black}\- in this guide you need to substitute \[planetssuite:FILENAME\] or \[planetssuite:VERSION\] with the appropriate filename or version{color}
h3. Preparing for installation
h4. 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]
{quote}
{color:#ff0000}{*}NOTE: the official PDF documentation advises to use JDK 5, but you need Java JDK 6, otherwise some parts will not compile.*{color}
{quote}
h4. 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/|http://ant.apache.org/bindownload.cgi]
Install using apt: sudo apt-get install ant ant-optional
h4. 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.
{noformat}
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
{noformat}
Don't forget to test the path and environment-variables by logging out and in again and echoing the variables, e.g. *echo $PATH*.
h4. 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:
{noformat}
svn co https://planets-server.svn.sourceforge.net/svnroot/planets-server/trunk ~/planets-server
{noformat}
Checkout the Planets Suite sourcecode:
{noformat}
svn co https://planets-suite.svn.sourceforge.net/svnroot/planets-suite/trunk ~/planets-suite
{noformat}
_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 (~)._
h3. 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*
{code}
planets-server.root=/home/planets/planets-server-compiled
{code}
*Directory where the Planets Server configuration should be stored*
{code}
planets-server.config.dir=/home/planets/planets-server-compiled/server/default/conf/planets
{code}
*Hostname of the Planets Server*
{code}
planets-server.host=planets.local.lan
{code}
*HTTP-port of the Planets Server*
{code}
planets-server.port=8080
{code}
*HTTPS-port of the Planets Server*
{code}
planets-server.ssl.port=8443
{code}
*Username and password of the DerbyDB database which will be created during installation*
{code}
planets-server.db.useradmin.user=PlanetsDBAdmin
planets-server.db.useradmin.pw=changeMe
{code}
*Email configuration settings and options*
{code}
# 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
{code}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)\*
{code}
if_server.dir=/home/planets/planets-server-compiled
{code}
*Directory where the Planets Server configuration is stored (same as planets-server.config.dir in planets-server.properties)*
{code}
if_server.conf=/home/planets/planets-server-compiled/server/default/conf/planets
{code}
*Directory that stores the Data Registry configuration*
{code}
if_server.doms.config.dir=/home/planets/planets-server-compiled/server/default/data/planets/dom-config
{code}
*Hostname and ports of the Planets Server (same as configured in planets-server.properties)*
{code}
if_server.host=planets.local.lan
if_server.port=8080
if_server.ssl.port=8443
{code}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*
{code}
ant deploy:planets-server
{code}
This should complete with the message "BUILD SUCCESSFUL"
*Create DerbyDB Database*
{code}
ant create:dbs
{code}
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:
*Deploy Framework*
{code}
ant deploy:framework
{code}
This should complete with the message "BUILD SUCCESSFUL"
*Deploy Services*
{code}
ant deploy:services
{code}
This should complete with the message "BUILD SUCCESSFUL"
*Deploy Testbed*
{code}
ant deploy:testbed
{code}
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.
h3. Running Planets Server
Change to the bin directory where Planets Server and Planets Suite are installed.
{code}
cd /home/planets/planets-server-compiled/bin
{code}
Start the server with the following command:
{code}
./run.sh -b0.0.0.0
{code}"-b0.0.0.0" is to have the server broadcast on all available network adapters, otherwise it will only broadcast on 127.0.0.1 (localhost). You can also replace 0.0.0.0 with a specific IP-address.
Alternatively start the server with the following command to detach the process from the current terminal:
{code}
nohup ./run.sh -b0.0.0.0 &
{code}
Note: all output will be written to 'nohup.out'.
Further reading: [PT:Configure Planets Server storage folder]