Grog setup and configuration

In this tutorial we are going to install and configure the prototype for Grog, a PaaS based on OSGi for Public Administrations and private networks.


We successfully tested it on the following OSs: Windows XP SP3, Ubuntu 10.04-11.10, CentOS 5.2; it can even run distributed on these OSs at the same time. To function properly the prototype requires these components:

• Java JDK 7, NOT JRE
• an accessible MySQL server 5.5
• an accessible RabbitMQ server (which also requires Erlang)
• an accessible Openfiler server with WebDAV access enabled
• a properly populated hosts file
• Grog modules configuration

Aside from Openfiler which must be installed on its own machine or Virtual Machine, all other components can be installed on the same machine. Alternatively, you can configure your own machine to act as a WebDAV server and use it instead of OpenFiler just by changing some configuration parameters (described later).

Download the prototype implementation source here or from grab it from GitHub.

Java configuration:


Once Java JDK 7 is installed, make sure it is correctly set as default by opening a terminal and typing:


java -version


If the output is not telling you that the version is 1.7.0 (or greater) or that it is using the JRE instead of the JDK, configure it properly. It is possible that you have multiple JDK/JRE versions installed and your system is still using an old one.

You must also set the LD_LIBRARY_PATH system variable to include "." in order to tell Java to look for libraries in the folder where the process is running as well. On Linux you can put the following in your ~/.bashrc file:

export LD_LIBRARY_PATH="."

On Windows you can browse to Start->Control Panel->System->Advanced->Environment Variables.. and add it there.

You will need Java JDK 7 on every machine running Grog.

MySQL server 5.5 configuration:

Note that you should not have any problems even if you use older MySQL versions, but we didn't test on them.

Once MySQL server is installed and started, configure it to be accessible remotely at your machine's IP and not only on localhost. You can use multiple graphical tools or from command line type:

mysql -u root -h 127.0.0.1 -pYOUR_PASSWORD

if you did not set a password, do not add the -p parameter. When the mysql console appears, type:

create user 'root'@'YOUR_IP' identified by 'YOUR_PASSWORD';

You can verify that everything went right by exiting the mysql console (either "quit" or "exit") and then:

mysql -u root -h YOUR_IP -pYOUR_PASSWORD

If the mysql console appears again, you're good. Also, MySQL uses the 3306 port for incoming remote connections, so make sure it is free.

You now have to create the required databases and tables by issuing the following commands at your mysql console:

create database aee;
use aee;
create table sandboxes(id int AUTO_INCREMENT, sID varchar(50) unique not null, appID varchar(50) not null, consolePort varchar(5), configDir varchar(200) not null, logFile varchar(200) not null, errFile varchar(200) not null, PID varchar(4), clientPort varchar(5), primary key(id));

create database management;
use management;
create table aee(id int AUTO_INCREMENT, ip varchar(15) unique not null, primary key(id));
create table cc(id int AUTO_INCREMENT, ip varchar(15) unique not null, primary key(id));
create table rr(id int AUTO_INCREMENT, ip varchar(15) unique not null, primary key(id));
create table apps(id int AUTO_INCREMENT, appID varchar(50) not null, location varchar(200) not null, unique index(appID, location), primary key(id));

create database networking;
use networking;
create table routing(id int AUTO_INCREMENT, appID varchar(50) not null, ip varchar(15) not null, clientPort varchar(5), consolePort varchar(5) not null,unique index(appID, ip, consolePort), primary key(id));

You can find the SQL scripts inside the aee, management and networking folders of the prototype.

For our example, a single MySQL server will be more than enough, you will not need to install it on every machine running Grog.

Erlang configuration:

Besides installing Erlang, you should not have anything more to do as it should be already good to go.

You will need to install Erlang on the same machine running RabbitMQ server.

RabbitMQ server configuration:

Again, after RabbitMQ server is installed, you should already be all set. On Windows, you will be unable to start it if the Workstation service is disabled. Check it by pressing Windows key+R, then type services.msc and enable/start the service if needed.

You may also encounter an error: "Unable to connect to node: node down", which you should solve by making sure that the C:\Windows\.erlang.cookie and C:\Documents and Settings\YOUR_USERNAME\.erlang.cookie files are exactly the same; if not, copy one in the other folder and you're ok.

For our example, a single RabbitMQ server will be more than enough, you will not need to install it on every machine running Grog.

Openfiler server with WebDAV and LDAP configuration:

You can use any WebDAV server here, but we tested on Openfiler. We downloaded the appropriate .iso from the website, then installed it on a VirtualBox virtual machine (but you may use whatever you wish) with 512MB of ram and 10GB of disc space plus 100GB of secondary HDD (though in our example something like 1GB as secondary HDD will be more than sufficient).

Once Openfiler is installed and started, you can configure it by accessing it though its web interface at https://OPENFILER_IP:446 with username opernfiler and password password.

You will now have to configure it with a storage unit (the secondary HDD) and enable WebDAV access on it. You will have to enable the LDAP server as well. If you need, you can consult another guide here.

NOTE: as of now, you are required to perform the following steps manually, as I'm still working on the interface.

You can grab the example server and client applications and store them on Openfiler. On Linux you should be able to access any WebDAV folder directly from Places->Connect to Server.. while on Windows you can use a client such as BitKinex.

Once you successfully uploaded the files, you must update the DB to point to them. Connect to your mysql console and type:

use management;
insert into apps values(null, "it.eng.test.remote.ds.hello", "URL_ON_OPENFILER"),(null, "it.eng.test.remote.ds.helloconsumer", "URL_ON_OPENFILER");

with URL_ON_OPENFILER the full URL, from http to .zip

And DO NOT CHANGE the appID values. As of now, the appID of the service bundle must be exactly the same as the Required-Bundle string from the client's MANIFEST. Also, altering those names may mess up the OSGi bundles configuration which is done via XML, but (i) it is not completed yet and (ii) I still need to properly test it.

Grog modules configuration:

You can download the latest build here if you do not want to compile it yourself. Copy everything into a folder C:\paas (Windows) or /paas (Linux) and be sure to maintain the folder structure. On Linux you will likely have to chmod them as well:

sudo chmod -R 777 /paas

Please do not lynch me for going 777.

Now you will have the following folders:

• aee - contains the AEE executable, its libraries and its configuration file
• aee_logs - where the AEE logs, errors and host info file will be stored
• apps - where the deployed applications will be downloaded before starting
• cc_logs
• hostControl - this module is only needed to overcome an OCCI issue which does provide any means to send commands to the newly started machines, forcing you to rely on configuration scripts, SSH or (like in our case) a custom client.
• hostControl_logs
• management - contains the CC executable, its libraries and its configuration file
• networking -  contains the RR executable, its libraries and its configuration file 
• rr_logs
• it.eng.paas.util.jar - not really needed as it is already packaged within the other jars

You can choose to run these modules even on different machines and OSs, as long as you configure them correctly.

hostControl

The hostControl module is used to receive TELNET XML requests from the CCs to start new modules on its machine and has to be started automatically when the machine boots by creating a startup script. If not using a OpenNebula/OCCI environment, it is not needed. Again, this is still a work in progress and the module has been tested only slightly.

Sample requests can be found under the test source folder. Telnet.java contains a method startModule() which sends a sample request to the hostControl module to start a new AEE on that host. It connects to it on the 9999 port and needs a fully filled .properties file to send along. You can just create one and point to its location. In reality, this operation is done directly by the CC, but again, not sufficient testing has been performed:

client = new Socket("MACHINE_IP_RUNNING_HOSTCONTROL", 9999);
Document asd = PaasUtilities.file2XML(new File("AEE_PROPERTIES_FILE"), "test");

AEE

The AEE module manages the sandboxes where the applications run. It is configured through its aee.properties file:

aee_deployed_apps_dir: ../apps/
aee_logs_dir: ../aee_logs/
aee_tenant_setup: false
aee_local_po_address: RABBIT_MQ_ADDRESS
aee_controller_recovery_retries: 5
aee_storage_user: OPENFILER_USER
aee_storage_pwd: OPENFILER_PASSWORD
aee_DB_user: MYSQL_USER
aee_DB_pwd: MYSQL_PASSWORD
aee_DB_URL: MYSQL_URL

When you're set, you can launch the AEE by browsing to its folder and issuing:

java -jar it.eng.paas.aee.jar aee.properties

The same goes for the other modules.

Should anything go wrong, the log in aee_logs contains every detail to solve it (hopefully). You can find example requests under the test source folder. Send*AppMessage.java are either to start or stop one of the applications uploaded on Openfiler; mind however that the client cannot be started if the service has not already been started as it will miss its dependency:

 factory.setHost("RABBITMQ_IP");
  channel.exchangeDeclare("RABBITMQ_IP", "topic");
  PaasUtilities.addXMLnode(xml, "appID", "APPID");
  PaasUtilities.addXMLnode(xml, "location", "OPENFILER_APPID_URL");
   channel.basicPublish("RABBITMQ_IP", routingKey, null, message.getBytes());

Networking:

The networking module is used to track which services are active where inside the platform. It is configured via the rr.properties file:

rr_local_po_address: RABBIT_MQ_ADDRESS
rr_logs_dir: ../rr_logs/

rr_DB_user: MYSQL_USER
rr_DB_pwd: MYSQL_PASSWORD
rr_DB_URL: MYSQL_URL 


If you start it before the AEE and then request the AEE to start the service application, you should see on the RR output or on its database table that he got and stored the information that a new service had become available at the AEE's IP.

Management:

The management module is used to manage the platform and the other modules, as well as receiving and satisfying users requests. It is configured via the cc.properties file:

cc_logs_dir: ../cc_logs/
cc_app_deploy_retries: 2
cc_cpu_deploy_percentage: 10
cc_ram_deploy_percentage: 10
cc_local_po_address: RABBIT_MQ_ADDRESS
cc_listener_port: 6666

cc_DB_user: MYSQL_USER
cc_DB_pwd: MYSQL_PASSWORD
cc_DB_URL: MYSQL_URL 

NOTE: Even if the CC is configured to check for and start any missing modules, I did not have time to extensively test it, so I recommend starting the AEE and RR modules before to avoid funny behaviour.

A sample request to ask the CC to start a deployed app can be found under the test source folder. Telnet.java contains a method startApp() which sends a sample request to the CC module to start a new application (which has to be already deployed on Openfiler) inside a suitable AEE.

client = new Socket("CC_HOST_IP", 6666);
     PaasUtilities.addXMLnode(doc, "appID", "APPID");
  Document asd = PaasUtilities.file2XML(new File("APPID_MANIFEST"), "manifest");

Along the request, it sends the application MANIFEST. For this example, you should extract it somewhere then point to it. To fully appreciate the example, add any of the following lines at the end of it:

Require-OS: OS_NAME (e.g. Linux or Windows XP)
Require-Arch: OS_ARCH (e.g. i386 or x86)
Require-RAM: RAM_AMOUNT (in MB, e.g. 1024)
Require-Hz: PROCESSOR_SPEED (in Hz, e.g. 1000)
Require-Cores: PROCESSOR_CORES (e.g. 2)

If you set these parameters correctly, the application will start. If you put non-satisfiable requirements, the application will not be started and you will be informed of which requirement could not be met. Remember that different Linux distros will identify themselves simply as "Linux" while Windows will present itself as "Windows XP", "Windows Vista" or "Windows 7". Moreover, the RAM is checked against the currently available RAM so if you have 128MB free and ask for more, the application will not start.

hosts file configuration:

Another critical step (if your network does not provide any sort of hostname-address translation) is to properly populate the machine's hosts file. On Windows you can find it under C:\Windows\System32\drivers\etc\ while on Linux it usually is under /etc/


In there you must write the IP-hostname pair for every machine used with the prototype. For example, assuming that you have:

• MySQL on 192.168.23.30 with hostname server
• Openfiler on 192.168.23.40 with hostname openfiler
• RabbitMQ on the same machine as MySQL
• Grog modules on 192.168.23.28 with hostname grog

Then you'll need to update only the hosts file on grog to include:

192.168.23.28 grog
192.168.23.30 server
192.168.23.40 openfiler

After all these operations, if any everything goes well, you will be able to start the client and server applications and you should see two new folders under C:\paas\apps or /paas/apps called as the two running applications.
Inside them there will be two more folders; one with a long, incomprehensible name, and the other called logs. Inside the former there is the sandbox running the application, while in the latter you will find the error and log files.
If you go through the client log, you should see the output generated after having contacted and consumed the service, something like "Got proxy IHello..." and "Hello from SERVICE_IP".