Installation Manual
From Empweb
Contents[hide]
|
Empweb Installation | Release 1.5 | Feb 2007
Short Version (only for Windows)
The Windows version of the demo release includes an installer, so the detailed instruction of the next sections are not needed. Everything is done automatically.
Before starting the installation, please install the following requirements:
- MySQL 5.0 or later with InnoDB support.
- Java Development Kit 5 (1.5.x)
- Jetty 5.1.11 or later (untested with Jetty 6 series)
- Just unzip the file somewhere in your hard drive
After installing the required software, run the Empweb installer and follow the steps.
The demo version installs demo databases for users and objects.
After the system is running, you will have to initialize the transaction database which includes a few sample transactions. To do this login as administrator (user:admin and password:empweb), and go to the administration/bases tab. Answer "yes" to confirm, and the system will be ready to use.
Note: The transaction database is stored under MySQL, so the MySQL service must be running, and the user "root" with no password must have permission to create the database. If you want to use a different user/password, you will have to configure the engineconf.xml file and change the settings for the TRANSA database. For more details read below, the section about MySQL configuration.
Introduction
This document describes the installation procedure for Empweb Release 1.5.
Empweb consists of three subsystems (from top to bottom):
- Web User Interface (GUI)
- Empweb Engine
- Database Web Services
The three subsystems can be deployed separately (in different machines, for instance). This installation guide explains how to install the whole package in one computer.
Requirements
Empweb is Java based. The current implementation of the Empweb transaction database is based on MySQL database. The Web User Interface is Java and JSP (Java Server Pages) based.
The basic requirements are:
- Java Development Kit 5 (1.5.x)
- Jetty 5.1.11 or later (untested with Jetty 6 series)
- Mysql 5.0 or later with InnoDB support.
If you are using Isis user/object databases under Linux using GCC 4 or later, make sure that you have the compat-libstdc++ libraries installed.
Under Fedora Core 5 you should run the following install command:
yum install compat-libstdc++-33 compat-libstdc++-296
Under Ubuntu 7 you should run the following install command:
sudo apt-get install libstdc++2.10-glibc2.2
If you download the Empweb sources, you need Apache Ant to compile:
- Apache Ant (http://ant.apache.org)
Note: The current release's startup scripts have been configured for Jetty. This does not mean that a different servlet container cannot be used.
Included with the distribution are:
- JXPath 1.2 (custom modified version)
- Axis 1.2
- Apache implementation of JSTL 1.1 (JSP 2.0 Standard taglibs)
- Groovy 1.0
- Isis DLL
Please contact (empweb AT kalio.net) if you have problems with this installation
Step by Step Software Installation
The following procedure describes a complete installation of the 3 modules of Empweb (GUI, Engine and DB) on the same computer.
1 | Java JDK
Download and install JDK 1.5 from http://java.sun.com/javase/downloads/index_jdk5.jsp
Note: This must be the Java SE JDK (Development Kit), NOT the JRE (Runtime Environment)
The recommended installation locations are:
- Linux: /usr/java/jdk
- Windows: C:\java\jdk1.5
Note: Untested with Java 6 (1.6) versions.
2 | Jetty 5.1
Download and install Jetty 5.1.11 or later from http://dist.codehaus.org/jetty/jetty-5.1.11.zip
The recommended installation locations are:
- Linux: /usr/java/jetty
- Windows: C:\java\jetty-5.1.x
Just unzip the file under the chosen location. This will be your Jetty home directory.
Note: Untested with Jetty 6.x series.
3 | Empweb
1. Download the latest Empweb distribution from http://kalio.net/downloads/empweb
Expand the distribution package. The recomended installation locations are:
- Linux: /var
- Windows: C:\
After expanding, you will have:
- Linux: /var/empweb
- Windows: C:\empweb
Note: We will refer to this directory as <empweb.home>
This is part of the directory structure that you will find under <empweb.home> :
common/ # common files necessary for the three subsystems
/etc # startup scripts and common configurations
/ext # common third-party libraries
/lib # common Empweb code
/xml # Empweb's XML Schemas and WSDL file
dbws/ # database web services subsystem
/conf # dbws configurations
engine/ # Empweb Engine subsystem
/conf # Engine configuraion and transaction pipelines
/trans_rules # Built-in compiled rules used in the transaction pipelines
gui/ # Web-based graphical user interface
/resources # CSS, images, etc.
/conf # GUI configuration and translation (i18n) files
2. Edit and configure Empweb startup script:
Note: If you used the Windows quick installer, these variables have been already configured according to what you chose during installation and desktop icons were created for easy launching of the system. In this case, you can skip this section.
Under <empweb.home>/common, there is a directory called "etc" which contains startup scripts and configurations for the servers.
- Linux: <empweb.home>/common/etc/empweb.sh
- Windows: <empweb.home>\common\etc\empweb.bat
The Jetty Server will start three listening TCP ports, one for each of Empweb's subsystems. The Jetty configuration for each subsystem is in the files: ewengine-jetty.xml, ewdbws-jetty.xml, and ewgui-jetty.xml. If you don't wish to change the standard ports (8086, 8085, and 8080 respectively) and don't need to enable HTTPS/SSL then you don't need to touch these configurations.
Open the startup script for your platform (.bat or .sh) in a text editor and modify the necessary environment variables at the beginning of the script.
The three variables and their default values are:
EMPWEB_HOME=@EMPWEB_HOME@ JETTY_HOME=@JETTY_HOME@ JAVA_HOME=@JAVA_HOME@
The meaning of these variables is:
- EMPWEB_HOME is the root directory of the Empweb installation (also referred to as "empweb.home" from Java and other configuration files)
- JETTY_HOME is the root directory where you installed Jetty.
- JAVA_HOME is the root directory of your Java SDK/JDK installation.
You may also want to change some of the other variables if you know what you are doing.
There is a init.d script available. It follows Redhat/Fedora configuration style.
4 | Sample databases
This release includes sample Isis databases for "users" and "objects". These are the "bibusu" and "bibliv" taken from EMP 3.3 and adapted to the inverted index tags that Empweb needs; and the users have current validation dates.
For Linux they can be found under:
- $EMPWEB_HOME/db/isis/users
- $EMPWEB_HOME/db/isis/objects
For windows they can be found under:
- %EMPWEB_HOME%\db\isis\users
- %EMPWEB_HOME%\db\isis\objects
5 | MySQL
This version of Empweb uses MySQL to store transactions, calendars and user/object profiles.
Mysql needs to be up and running to complete the installation.
Note: You must have a user with full access permission to the transa (or transademo) database used by Empweb. The user and password must be configured in <empweb.home>/engine/WEB-INF/conf/engineconf.xml
By default, engineconf.xml comes configured to use user "root" with empty/no password.
Database Web Service Configuration
The Empweb DBWS subsystem already includes an easy way to offer Web Services for Isis, generally used for user and object databases.
The database web services are normally under <empweb.home>/dbws/WEB-INF which contains two configuration directories:
- axis contains the axis deployment configurations for each Database Web service.
- conf contains the Empweb configuration for each DBWS using XML.
Each DBWS configuration file specifies:
- database engine (only "isis" supported at this moment)
- database type ("users" or "objects")
- location (directory of the Isis db)
- database name/collection (the base name of the Isis .mst, which must reside under the "location" given above)
- An XSLT section specifying the transformation from the raw XML (Empweb's Isis XML) into the XML needed by the engine (MODS for objects or Empweb Users XML for users)
- A query section that maps the standard Empweb query names to the indices/fields used in the real database.
Configuring a database.
Empweb is not a user/object database administration tool. If you are using the demo distribution, you may use the pre-configured demo databases and skip this section. If you want to use Empweb with your own databases, please keep reading.
The following steps are required to create a new database web service for an existing Isis database:
1. Create the database configuration file
This file defines mainly:
- the database type ("isis").
- the stylesheet used to transform from the database to the XML schema used by empweb.
- the mapping of Empweb query names to the inverted tags used in your db.
Some examples can be found in the <empweb.home>/dbws/WEB-INF/conf directory.
2. Deploy the Axis web service.
After creating the configuration file, the web service has to be deployed in the DBWS servlet.
(TODO: Explain how to deploy a new dbws using an Axis ant target or similar, or direct edition of server-config.wsdd!!!)
A script will be provided in the future. For the moment it can be done manually by editing the <empweb.home>/dbws/WEB-INF/server-config.wsdd file. Some example configurations are included in this file for reference. Copy one of the _service_ elements named EmpwebObjectsService or EmpwebUsersService and change it's name and configFile parameter.
3. Add the database to the Empweb engine configuration registry
Add the new DBWS created to the Engine configuration file <empweb.home>/engine/WEB-INF/conf/engineconf.xml.
The type of base added has to be _users_ or _objects_.
Please reffer to the "Engine Configuration" section for further explanations.
Empweb Engine Configuration
The Engine configuration files are in <empweb.home>/engine/WEB-INF/conf
The main configuration file is "engineconf.xml" which declares:
- All the transactions registered in this installation, their names and respective pipeline configuration files.
- All the databases registered in this installation and their logic names, types, etc.
- The EmpwebDB implementation class and any configuration it needs.
engineconf.xml is thoroughly documented in the file itself.
The transa database backup directory must exist.
The other important files in this directory are the pipeline configuration files (registered in engineconf.xml). Their format is specified in the empweb-transaction-1-0.xsd schema.
Web User Interface Configuration
The Web graphical interface (GUI) resides in <empweb.home>/gui and it consists of Java Server Pages (JSP) files, along with some HTML, CSS, graphics, translations, etc.
The configuration is under <empweb.home>/gui/WEB-INF/conf/config.properties which specifies the Web Service URI's for the different subservices of the Engine (query service, admin service, transaction service...)
It also specifies the gui.default_locale property in order to have a default language/country. For example, for Spanish you write: gui.default_locale=es
for United Kingdom English you would write: gui.default_locale=en_UK
GUI Translations
The different translations are in the "ewi18n" subdirectory and are written in standard Java property file format.
There is a "core" subdirectory for core Empweb messages and GUI lables and there's a "local" directory where the administrator can customize some presentations, and provide description for profile limits and custom rule messages.
Please refer to the documentation for detailed explanations.
Starting and Initializing the System
To start the system the following subsystems have to be started:
- Mysql database that stores Empweb data.
- Empweb.
To start Mysql refer to the documentation.
To start empweb execute:
- Linux: <empweb.home>/common/etc/empweb.sh start
- Windows: <empweb.home>\common\etc\empweb.bat start
If you've copied the init.d script, in a Redhat or Fedora system you can use service empweb start.
Database initialization
The first time the system is run, transaction and configuration database for Empweb has to be initialized.
NOTE: this procedure deletes all existing information in the transaction databases. If you are using the demo distribution, the database will be reset to the few pre-defined demo transactions.
To perform this procedure, once the Empweb and the MySQL database has been started, perform the following steps:
- Login to the site http://yourdomain:8080/empweb.
- user: admin
- pass: empweb
- Click on the administration tab and then click on bases
- Confirm that you want to initialize all databases.
Logs
Current configuration generate logs in <empweb.home>/logs directory.
This defaults can be changed through the JETTY_CONSOLE variable in the startup script.
License
This documentation is Copyrighted by Kalio.net. All rights reserved.
![[Main Page]](./installation_manual_files/logo_kalio_solo_50x50_transp.png){kind=logo}