Introduction

This document describes the steps to perform to install ProLinga System Builder version 0.0.2 binary Deb packages on the Ubuntu 9.10 (Karmic Koala) platform and is intended for the following product releases:

If you are on a different release, please go to the matching installation page. This document is written for the i386 architecture. If you use Ubuntu on a different architecture, you have to replace the i386 with your arch notation.

Upgrading

At the moment, the contents of the 4GL application repository will be overwritten when upgrading an existing prolinga-repository installation. To move your applications to the new version, you first have to unload them from the repository. To do so, download this Repository Command and change the Application attributes stock to the name of your application. Then run the following command: 

$ /usr/bin/prolingarepexec --in /home/backup/appn_dump.xml --out /home/backup/myAppn.xml

This will create a file containing all the objects of your application. Repeat this process for all your applications.

After upgrading your application, you can load your application on a similar way. Open the file myAppn.xml and in the Command element in the beginning of the file replace Name="Get" with Name="Put" and replace Mode="Response" with Mode="Request". After that run the following command: 

$ /usr/bin/prolingarepexec --in /home/backup/myAppn.xml --out /home/backup/output.xml

Repeat this for all your applications. An automatic upgrade feature will be implemented in following releases. It is good practise to periodically archive your application this way. Physically, the repository lives in /share/prolinga/system and the file name is system.

Prerequisites

ProLinga products are built around numerous open source packages. Most of these packages like libxml2 or libglade are part of the major standard GNU/Linux distributions. When trying to install the ProLinga Deb packages, a message will appear if a dependent 3rd party package is not available. In that case you can get the missing package from your distribution CD, you can download it from the web and install it on your machine, or you can use the apt-get command.

A package that should be mentioned is:

These packages are not distributed by Xobas Software, but you can get them from your Ubuntu 9.10 distribution source. As mentioned before, easiest to use the apt-get command. Alternatively, you can download them from a Ubuntu mirror.

There are a couple of packages that are not shipped with Ubuntu 9.04 GNU/Linux distributions that ProLinga projects rely on. They are:

These packages have been compiled and built in-house and are availabe as Deb packages at http://download.xobas.net/prolinga/linux/ubuntu/9.04. Download these packages for your architecture and install the packages in this order:

  1. libxqilla_2.1.4-3karmic_i386.deb
  2. xqilla_2.1.4-3karmic_i386.deb
  3. libdbxml_2.4.16-3karmic_i386.deb
  4. dbxml-utils_2.4.16-3karmic_i386.deb
  5. libgda41-common_4.1.1-2karmic_all.deb
  6. libgda41-4_4.1.1-2karmic_all.deb
  7. libgda41-bin_4.1.1-2karmic_all.deb
  8. libgda41-mysql_4.1.1-2karmic_all.deb
  9. libgda41-postgres_4.1.1-2karmic_all.deb (only required when MySQL database is going to be used.)
  10. libgda41-sqlite_4.1.1-2karmic_all.deb (only required when PostgreSQL database is going to be used.)

You do not need the -devel- packages for a successful ProLinga installation. You do however need to have root privileges to install the Deb packages.

Ubuntu 9.10 does not create the directory /usr/tmp by default. If this directory does not exist, manually create it and chmod it to 777.

Database setup

Although access to many different databases is available through libgda technology, only PostgreSQL and MySQL have been verified to work at this stage. Instructions of how to prepare a PostgreSQL and MySQL database are given in the next two sections.

Preparation of PostgreSQL database

A correctly configured PostgreSQL database should be running on your system. For PostgreSQL specific installation and configuration issues, visit the Web Site of PostgreSQL for any help, as this falls outside the scope of this document. You can check if PostgreSQL is installed by typing the following at the command line: 

$ dpkg -l | grep postgresql

This should return at least the entries " postgresql-8.4", "postgresql-common" and "postgresql-client-8.4".

The daemon can be started by typing: 

$ sudo /etc/init.d/postgresql-8.4 start

as root user from the command line.

Set a password for the user "postgres".

Some configuration files have to be modified. Go to the directory "/etc/postgresql/8.4/main" and edit file pg_hba.conf. Change the line:

host    all         all         127.0.0.2/32         md5

to:

host    all         all         127.0.0.2/32         trust

This enables the Postgres client to connect to the localhost. Do the same for the IPv6 entry and change line:

host    all         all         ::1/128         md5

to:

host    all         all         ::1/128         trust

In the same directory edit the file postgresql.conf, search for the string client_min_messages and add a line like this:

client_min_messages = warning

Messages of the type NOTICE must be avoided (libgda issue). Make sure the line is not commented out (#).

After these changes, you have to restart the postgresql daemon by typing:

$ sudo /etc/init.d/postgresql-8.4 restart
Create database

The default ProLinga installation uses a demo database called stock. To create this database in postgresql, logon as user postgres (or su - postgres) and type:

$ createdb stock

You should get a response "CREATE DATABASE" indicating that the database creation was successful.

Create user

The default ProLinga installation uses a database user called prolinga. To create this user in postgresql, logon as user postgres and type:

$ psql stock

At the psql prompt type:

stock=# CREATE USER prolinga;

Exit psql.

stock=# \q

Double check if you can logon to postgres now as the prolinga user. From the command line type:

$ psql -h localhost -U prolinga stock

If you now type 

stock=> \l

you should see the database stock among others (if any).

For more PostgreSQL specific details, please check their documentation at http://www.postgresql.org.

Preparation of MySQL database

A correctly configured MySQL database should be running on your system. For MySQL specific installation and configuration issues, visit the Web Site of MySQL for any help, as this falls outside the scope of this document. You can check if MySQL is installed by typing the following at the command line: 

$ dpkg -l | grep mysql

This should return at least the entries "mysql-common", "mysql-server" and "mysql-client-5.1".

The daemon can started by typing: 

$ sudo /etc/init.d/mysql start

No additional changes of MySQL configuration files are needed as a default installation works correctly.

Create database

To create the database in MySQL, logon to mysql client as the database administrator user (by default is this user root) and type:

$ mysql -h localhost -u root -p mysql

If asked for a password, just press Enter or enter the password that has been set at MySQL installation time.

The database can then be created as follows:

mysql> CREATE DATABASE stock;

If this step went OK, you will see a result as follows:

Query OK, 1 row affected (0.06 sec)
Create user

The user can be created as follows:

mysql> GRANT ALL ON stock.* TO 'prolinga'@'localhost';

In this example setup the user is given all privileges for the stock database. In production environments, stricter security measures should probably apply.

For more MySQL specific details, please check their documentation at http://www.mysql.com.

Creating a Data Source

Xobas ProLinga System Builder uses gnome-db (libgda) technologies to connect to data providers as PostgreSQL and MySQL. To be able to connect to a database, a Data Source needs to be created that holds details as database name, user name, tcp port etc. The easiest way to create this is to run the gnome-db utility gnome-database-properties-3.0 that comes as part of the libgnomedb package. Make sure you run this application as the user that will run the ProLinga environment, or for ProLinga Networked configurations, the user that started the prolingadatd daemon.

Go to the command line and type:

$ gnome-database-properties-3.0

This brings up the gnomedb database properties tool. Click on the tab Providers and check that your data provider (PostgreSQL or/and MySQL) is in this list. If they are not in the list, go a bit back in this document and double check that you have installed all the libgda and libgnomedb packages as required.

Click on the tab Data source where you will see a list of configured data sources. If this is the first time you run this tool, this list is probably empty or contains just a Default entry.

Go to pulldown menu Data source and click New DataSource. This will start a druid that guides you through a series of screens to collect all the data needed. Click Forward. On the screen General Information, enter the following details to create a data source to run the ProLinga demo application stock:

Click Forward. Do NOT select the checkbox 'Create a new database', but leave it empty and click Forward. Fill out the fields on screen Provider Parameters as outlined below. Where no data is given, leave the field blank.

The values for PostgreSQL

The values for MySQL

Click Forward and then Apply to confirm all changes and to create the Data Source.

You can now test if the newly created data source works OK. In the main screen where all data sources are listed, select the new data source stock. Go to pulldown menu Data source and click Properties. You should see here all the details you just entered. Click on the button Test. A new screen comes up, titled Login for stocksql. Press the Connect button. If all is OK, you should get a message "Connection successfully opened". Press OK to confirm that message. To further check, press the Browse button and all tables of the database will be listed. If your database does not contain any tables yet, you will see an empty screen. If you get any type of error, something went wrong while creating the data source. Go back in this document and try again.

This ProLinga release ships with a special libgda41 package, since this is not available yet as part of the Ubuntu distribution. This libgda41 package is installed in the /opt/libgda41 directory. Since we are working with a non-stock libgda version, the just created libgda configuration file ~HOME/.libgda/config, should be copied to /opt/libgda41/etc/libgda-4.0/config. The file ~HOME/.libgda/config should be made empty as follows:

<xml version="1.0"?>
<libgda-config>
	<!-- Leave empty -->
</libgda-config>

Once libgda > 4.1.1 is shipped with Ubuntu, this work-around will no longer be required.

Choosing the correct ProLinga System Builder installation type

ProLinga products can be setup and compiled in many different ways. For the binary (Deb) package distribution, the following installation types are available:

  1. Stand-alone installation. Choose this type of installation if you want to install all products on a single machine for local development.

  2. Enterprise installation. Choose this type of intallation if you want to connect to the ProLinga environment from more that one machine and/or if you want to use multiple servers as database server, application server etc.
Stand-alone installation

The stand-alone installation is very straight forward. Please download and install the packages (as root user) in this order:

  1. prolinga-calc_0.0.2-1karmic_i386.deb
  2. prolinga-soap_0.0.3-1jaunty_i386.deb
  3. prolinga-repository_0.0.2-1jaunty_i386.deb
  4. prolinga-validate_0.0.2-1karmic_i386.deb
  5. prolinga-data_0.0.2-1karmic_i386.deb
  6. prolinga-run_0.0.2-1karmic.sa_i386.deb
  7. prolinga-web_0.0.2-1karmic_i386.deb (only required if you want browser access to 4GL logic)
  8. prolinga-doc_0.0.2-1karmic_i386.deb (only required if you want a local copy of the ProLinga documentation in /usr/share/prolinga)

Double check that you pick the sa version of prolinga-run and not the net version. Now you are ready to start ProLinga System Builder. Please make sure that the first time you run the product you are NOT a root user, since cache and log files will otherwise get wrong privileges. This will be fixed in further releases.

Go to your home directory and type:

$ prolinga

If all went well, you will see the ProLinga logon screen. You can enter the application on 3 different levels:

  1. end-user: type guest in the user name box and type stock in application name box the press OK.
  2. developer user: type developer in the user name box and press OK.
  3. administrator user: type "administrator" and press OK.

To build the database tables parts and groups of the demo application stock, open this application in developer. Then click on the button Table on the tool palette, open the table, click on the Data Manager tab and press the Build Database Table button. This will build an empty table in your database. After building the tables, you can now go back to the ProLinga logon screen and run stock as end-user guest and you should be able now to enter data into the database.

Enjoy!

Enterprise installation

With an enterprise installation, the various ProLinga components can be setup as Web Services on one or more machines.

Repository

Download and install the packages on the machine that you want to host the application repository in this order (as root user):

  1. prolinga-soap_0.0.3-1jaunty_i386.deb
  2. prolinga-repository_0.0.2-1jaunty_i386.deb
  3. prolinga-repository-server_0.0.2-1jaunty_i386.deb

Check the values in configuration file /etc/prolingarepcfg.xml

Validate

Download and install the packages on the machine that you want 4GL validation to take place (most likely application server) in this order (as root user):

  1. prolinga-soap_0.0.3-1jaunty_i386.deb
  2. prolinga-validate_0.0.2-1jaunty_i386.deb
  3. prolinga-validate-server_0.0.2-1jaunty_i386.deb

Check the values in configuration file /etc/prolingavalcfg.xml

Data

Download and install the packages on the machine that hosts your database or where your database client is installed in this order (as root user):

  1. prolinga-soap_0.0.3-1jaunty_i386.deb
  2. prolinga-data_0.0.2-1jaunty_i386.deb
  3. prolinga-data-server_0.0.2-1jaunty_i386.deb

Check the values in configuration file /etc/prolingadatcfg.xml

Run (Desktop)

Download and install the packages on all the machines that needs to connect to the ProLinga environment (either developer user as end-user) in this order (as root user):

  1. prolinga-calc_0.0.2-1jaunty_i386.deb
  2. prolinga-soap_0.0.3-1jaunty_i386.deb
  3. prolinga-run_0.0.2-1jaunty.net_i386.deb

Check the values in configuration file /etc/prolingaruncfg.xml

Run (Server)

Download and install the packages on the machine that you want being the application server to provide access to Web Server etc in this order (as root user):

  1. prolinga-calc_0.0.2-1karmic_i386.deb
  2. prolinga-soap_0.0.3-1karmic_i386.deb
  3. prolinga-run_0.0.2-1karmic.net_i386.deb
  4. prolinga-run-server_0.0.2-1karmic.net_i386.deb

Check the values in configuration file /etc/prolingaruncfg.xml

Web

Download and install the packages on the machine that runs your Web Server (Apache for instance) to provide browser access to 4GL logic in this order (as root user):

  1. prolinga-soap_0.0.3-1karmic_i386.deb
  2. prolinga-run_0.0.2-1karmic.net_i386.deb

Check the values in configuration file /etc/prolingawebsvc.xml