| | | Fisterra Distribution Reference Manual | |
|---|
We will use YELP for the user manual (yelp uses docbook). The directory of the user manual is "fisterra_distribution/help/C", we must add here the information of the user manual, in the file fisterra_distribution.xml, at the moment this document is empty.
If you want view the user manual you have to do:
cd fisterra_distribution/help/C
make
yelp fisterra_distribution.xml
This manual describes the application installation and configuration processes.
This section describes the installation of Fisterra2 Distribution from Debian packages.
Fisterra2 is database independent due to its data access architecture based on libGda but its replication system requires PostgreSQL, a highly scalable, SQL compliant, open source object-relational database management system.
If you are installing from a debian package the configuration will try to configure the database. It is an automated process so you can jump to the next section. This task involves:
Create the database
Create an user for the database
Grant privileges to the user for the database
Create tables and views
Fill database with the essential data
In order to complete these tasks the configuration needs some information that must be provided by the user. This information includes:
Name of the machine that hosts the database
Name of the database
Name of the user that will access to the database
Password of the database user
All these parameters are explained in detail in the server configuration.
Fisterra2 needs a CORBA naming service running in a machine. The naming service is used by clients to locate CORBA objects and by servers to advertise specific CORBA objects. The basic function of the naming service is the association of names with object references. A server creates associations between names and object references for those CORBA objects that are intended to serve as initial points of contact. A client that knows the name of an object can then retrieve its object reference by querying the naming service.
Fisterra2 Distribution uses the INS (Interoperable Name Service), a revision of the original name service specification that allows clients to look up an object location using a key specified in a human-readable stringified name format. This feature was not supported by the ORBit2 implementation, so we have to develop a patch that was recently added to the ORBit2 CVS HEAD branch. Unfortunately this patch is not currently present in the official Debian packages so you have to install Igalia's ORBit2 packages.
Once downloaded and installed (see Installing Fisterra2 packages with the
.deb files or Installing Fisterra2
packages with apt to know how to do
it) download the script from here
and place it into /etc/init.d directory
in order to run it at system startup. Remember to add a link
to this script for each level of execution where the naming
service will be executed.
There are two ways for installing Fisterra2 Distribution from Debian packages. You can either download the Debian packages and install them with the dpkg command or use the apt tool to download and install with a single command. If you are going to use the apt tool you can safely skip this section and continue in the next section.
Fisterra2 Distribution can be downloaded from Sourceforge or Freshmeat repositories. There you can find the next packages:
fisterra2-distribution-client_0.4.0-1_i386.deb
fisterra2-distribution-server_0.4.0-1_i386.deb
fisterra2-distribution-doc_0.4.0-1_all.deb
libfisterra_0.1.200503021141-1_i386.deb
libfisterra-doc_0.1.200503021141-1_all.deb
liborbit2_2.12.2-1-igalia-1_i386.deb (with Igalia's patch for naming
resolution)
liborbit2-dev_2.12.2-1-igalia-1_i386.deb (with Igalia's patch for
naming resolution)
orbit2_2.12.2-1-igalia-1_i386.deb (with Igalia's patch for naming
resolution)
orbit2-nameserver_2.12.2-1-igalia-1_i386.deb (with Igalia's patch for
naming resolution)
All of them are necessary to run Fisterra2 Distribution except the doc-ended and dev-ended packages.
Once downloaded you can install all these packages with the following commands:
dpkg -i liborbit2_2.12.2-1-igalia-1_i386.deb
dpkg -i orbit2_2.12.2-1-igalia-1_i386.deb
dpkg -i orbit2-nameserver_2.12.2-1-igalia-1_i386.deb
dpkg -i libfisterra_0.1.200503021141-1_i386.deb
dpkg -i fisterra2-distribution-server_0.4.0-1_i386.deb
dpkg -i fisterra2-distribution-client_0.4.0-1_i386.deb
The last two packages requires some kind of configuration that will be explained in the section...
Fisterra2 Distribution can be downloaded from Igalia's apt repository. Just instert the next line
deb http://apt.igalia.com/ sarge fisterra
into your
/etc/apt/sources.lst. Then call apt-get
update in order to update your package lists. To install
Fisterra2 Distribution type apt-get install
fisterra2-distribution-client. This command will install the
necessary dependecies to run Fisterra2 Distribution. These
dependecies include among others:
fisterra2-distribution-server: the server
side of Fisterra2 Distribution
libfisterra: the development framework
postgres: the database
orbit2: the CORBA ORB used for communitations
The installation will try to configure some parameters needed by Fisterra2 Distribution to run. The section ... explains how to configure the client and the server. For a complete explanation of the parameters see the section...
There is still some stuff to do for getting a fully-featured Fisterra environment running in the configuration phase.
The installation proccess will try to configure some parameters for running Fisterra2 Distribution Server. In order to complete this tasks the user must input some data. The configuration is done in a wizard-like way, and is managed by debconf. Let's review the configuration process.
First of all the configuration asks for creating a new database and a database user. You probably will not have a Fisterra-ready database, so say yes to this question. After the configuration, the Fisterra2 package will try to create the database.
Even if you say yes or not to the previous question, the next step is to configure some database parameters. You have to input the database host, the database user and the database password. If you want the configuration to create the database for you in your localhost leave the database machine name as localhost. The password must be retyped in order to ensure that was correctly input the first time.
It is possible to log server messages in user
files instead of doing it into
/var/log/syslog because this file
is not readable by common users into a system. Say yes
if you want the log to be done in user files. This
files are located at user HOME
directory in two hidden directories
.fisterra2-distribution-client
and .fisterra2-distribution-server.
Fisterra2 Distribution has its own scheduler for performing some periodic tasks, like prices recomputing. The location of the scheduler wrapper could be defined, but you should not change its default location.
You can also specify the location of the scheduler logs. Like the previous question, there is not need to change the default value.
The four next questions are about CORBA communications. The first parameter is the prefix that will be prepended to all server objects. You can keep the default value but remember to specify a different value for each Fisterra server you want to configure.
The server object environment name is only useful when a single server is used for serve more than one store. It is safe to keep the default value.
The server objects host is the name of the machine where the server objects will be executed. This will be the name of the server machine, so replace localhost (the default value) with your server machine name.
The hostcode is an identificator of the server, this value should be different for each server.
The next two parameters specify the name of the machine where the replication server runs and the port used by the replication service. If you do not want database replication to a central server leave the default values unchanged.
The next step is configuring the name service used by CORBA. Like the previous question you have to input the name of the machine where the naming service runs and the port used by the service. You can run the name service in the same machine, in order to configure the name service see Configuring the name server.
Finally the user has to select the log level used by the application. This level specifies the verbosity of the log system from minimum (0) to maximun (7).
Once completed all tasks the configuration will create the database if needed. It also will create an user and the essential data.
The POS need some item data to run. This info is not essential to run Fisterra2 Distribution so is not inserted part of the essential data. If you want to test the POS you can use this script:
items_management {--server_config(1) } {--items-file(2) }
(1) server_config.xml
by default
(2) /usr/share/fisterra2-distribution/tests/items.xml
by default
in order to add some items and their prices to the database.
The installation proccess will try to configure some parameters for running Fisterra2 Distribution Client. In order to complete this tasks the user must input some data. The configuration is done in a wizard-like way, and is managed by debconf. Let's review the configuration process. Take a look at this note before.
First of all the configuration asks for the prefix for server objects. This name should be the same as the one specified here
The next parameter must be the same as the one specified here
The naming server configuration must be the same as the server one
There are three chioces for client application but currently all these three are the same, in the next releases each one will have different options. The only difference is that if cashier application is selected the next question is shown.
The SITEF system is used for credit card payments. It is currently not implemented.
There are two files for both client and server, used for configuring some parameters needed by the application:
client_config.xml
server_config.xml
The configuration parameters for the client are described bellow:
server_name - Server name identificator for CORBA communications.
store - Warehouse identificator where the client is located.
main_controller - This is the configuration interface file. This file defines the available windows and interface options that will be available in the client application. These options define the way a window is shown (embedded or modal), menu options and some more.
ticket-printer-device - printing device for tickets, for example /dev/lpt0. If you do not have a printing device you can also specify here the path of a file.
shop-register-sell-ticket-end-label - Label that is printed at the end of each ticket.
ticket-printer-7x9-columns - number of columns for ticket printing.
orb_naming_ior - Location of the CORBA service for the name resolution. the default is
-ORBNamingIOR=corbaloc:iiop:1.2@localhost:4444/NameService
Replace localhost with the name of the machine where the naming server runs.
default_user - default user in this station. This parameter coulb be removed
default_password- defaul password (clear text) for the default user in this station. This parameter could be removed.
The configuration parameters for the server are the next:
server_name - Server name identificator for CORBA communications.
store - Warehouse identificator where the server is located.
db_name - name of the database
db_hostname - name of the machine where the database runs.
db_user - user of the database.
db_password - password (in clear text) of the database user
scheduler_wrapper_path - Directory where is located the wrapper for the task scheduler.
scheduler_logdir - Logs directory for the task scheduler.
orb_naming_ior - Location of the CORBA service for the name resolution. the default is
-ORBNamingIOR=corbaloc:iiop:1.2@localhost:4444/NameService
Replace localhost with the name of the machine where the naming server runs.
local_naming_service: it is safe to keep the default value
central_replication_naming_service: Location of the CORBA service for the name resolution for database replication. It is safe to keep the default value
orb_host_name: This is the name where the server objects will run. Replacing localhost with the name of the machine where the server will run is enough in most cases.
log_level: sets the verbosity for the Fisterra2 log system, from 0 (minimum) to 7 (maximum).
debug_model: if is set to true, this parameter forces the application to log messages to user's files. This files are located at user hidden directories at users's home dir.
| << Implementation | Part I. API >> |