INSTALL

Building and Installing
=======================

Building
--------

IoTa uses Apache Maven for build automation (http://maven.apache.org).

A convenience building script is provided: make-all.sh.

Compilation of each module is achieved with this command:

    mvn compile

Maven will download all the necessary jar files and install them in a local
repository (usually ~/.m2/repository).

Installation of IoTa libraries in the local repository for further use (as
needed for several IoTa modules) is achieved with this command:

    mvn install

Note that this command also compiles the module if necessary.

Some of the modules provide unit tests and some of these tests need some
application to be running (eg. the tests for the IoTa-DiscoveryWS-Client
library need an up and running Discovery Web Service). To skip those tests,
use this command to compile or install:

    mvn -DskipTests install


You can manually install already downloaded jar files with this command:

    mvn install:install-file                 \
        -Dfile=sunxacml-2.0-SNAPSHOT.jar     \
        -DgroupId=net.sf.sunxacml            \
        -DartifactId=sunxacml                \
        -Dversion=2.0-SNAPSHOT               \
        -Dpackaging=jar

Note that this will be necessary for the sunxacml library as it’s on no
widespread known Maven repository. The jar file can be downloaded from the
SourceForge page for the project: http://sunxacml.sf.net

Here is a direct link: http://sourceforge.net/projects/sunxacml/files/maven/snapshots/net/sf/sunxacml/sunxacml/2.0-SNAPSHOT/sunxacml-2.0-SNAPSHOT.jar/download


Installing
----------

(All bracketted values `<name>` are place-holders.)

**The IoTa-Installer can help you to install and configure all the servers and
databases.**

All the applications and web applications have a `log4j.properties` file to
configure the logging output (file output, log format, log level, and so on).


### Applications

Get and extract the `<application>-<version>-bin-with-dependency.tar.gz`
tarball for the application.

Modify or create the configuration files (see the application `README` file
for a list and each file for comments).
A file in the current directory overrides the default version which is
embedded in the jar file.
You can extract the default commented version of the files from the jar file:

    jar xf <application>-<version>.jar application.properties

or

    unzip <application>-<version>.jar application.properties

Use the provided script to start the application.


### Servlet Container and SSL/TLS

A servlet container need to be installed.

For now, the IoTa-Installer knows only about Apache Tomcat (versions 6 or 7).
The IoTa-Installer can help you install and configure one.

In order to use SSL/TLS as a mutual authentication means for the IoTa web
applications and their clients, an SSL/TLS connector must be configured.

For Apache Tomcat 7, if you don’t use the IoTa-Installer, you need to add a
connector element similar to the following snippet in the file
`${CATALINA_HOME}/conf/server.xml`:

    <Connector protocol="HTTP/1.1"
               port="8443"
               maxThreads="200"
               scheme="https"
               secure="true"
               SSLEnabled="true"
               keystoreFile="${catalina.home}/conf/ssl/keystore.jks"
               keystorePass="changeit"
               keyAlias="if_more_than_one_key_in_keystore"
               keyPass="changeit"
               truststoreFile="${catalina.home}/conf/ssl/truststore.jks"
               truststorePass="changeit"
               crlFile="${catalina.home}/conf/ssl/revocations_list.pem"
               clientAuth="true"
               sslProtocol="TLS"/>

Or, if the Apache Portable Runtime library (APR) is installed and used on the
target system:

    <Connector protocol="HTTP/1.1"
               port="8443"
               maxThreads="200"
               scheme="https"
               secure="true"
               SSLEnabled="true"
               SSLCertificateFile="${catalina.home}/conf/ssl/server.crt"
               SSLCertificateKeyFile="${catalina.home}/conf/ssl/server.pem"
               SSLCACertificatePath="${catalina.home}/conf/ssl/clients/"
               SSLCARevocationPath="${catalina.home}/conf/ssl/revocations/"
               SSLVerifyClient="require"
               SSLProtocol="TLSv1"/>

Add the client's certificates to the Tomcat's truststore, with a command like:

    keytool -importcert -storetype "jks" -keystore "truststore.jks" -alias "key"  -file "client.cert"

The ETa, OMeGa and EpcisPHi applications need roles in `$CATALINA_HOME/conf/tomcat-users.xml`
to manage identity with TLS:

  * for ETa: <role rolename="eta_user"/>
  * for OMeGa: <role rolename="omega_user"/>
  * for EpcisPHi: <role rolename="ephi_user"/>

The names can be different depending on the configuration of
`<webapp-dir>/WEB-INF/web.xml`.

Each user who wants to request the services of ETa, OMeGa or the web interface
of EpcisPHi must be identified in `$CATALINA_HOME/conf/tomcat-users.xml`
and one or more roles must be attributed.
Each application using these services must be known.
The user (or application) is recognyzed by the Distinguished Name (DN) of
the certificate used to connect to the service.
The user roles (ETa and/or OMeGa and/or EpcisPHi) are determined by the
"roles" attribute and corresponds to the "rolename" above.

To add the ETa, OMeGa and EpcisPHi services to the user whose DN certificate is
"CN=foo", add to the `$CATALINA_HOME/conf/tomcat-users.xml` file:
<user username="CN=foo" password="" roles="eta_user,omega_user"/>

To log to the web interface of Epcis-PHi as "superadmin", who manages the user
accounts, you must use a certificate (generated by IoTa-Installer or keytool).
The DN of this certificate ("UID=superadmin" by default) needs to be similar to
the LDAP directory.
This user must be added to the previous file:
<user username="UID=superadmin" password="" roles="ephi_user"/>


### Web Applications

Get the `<application>-<version>.war` war file for the web application.

Deploy it in you servlet container (see the container documentation for
information). For Apache Tomcat, this can be done in several ways:

  1. manually dejar the war file in `$CATALINA_HOME/webapps`
  2. copy the war file in `$CATALINA_HOME/webapps` and let Tomcat deploy it
      (either at its next restart or while running if its autodeploy option is
      on)
  3. use the manager web application (http://localhost:8080/manager)
  4. use the deploy-tools
  5. use the Maven Tomcat plugin

Edit the configuration files in `<webapp-dir>/WEB-INF/classes/` (see the web
application `README` for a list and each file for comments).

Reload the web application or restart the servlet container.


### Web Applications with databases

1. The database

    Create the database for the application:

        CREATE DATABASE <app_db>;

    Create a specific user and grant them access rights:

        GRANT SELECT, INSERT, UPDATE, DELETE ON <app_db>.*
        TO <app_db_user>@localhost IDENTIFIED BY <app_db_password>;

    Create the tables:

        use <app_db>;
        source <app>_schema.sql;

    The file `<app>_schema.sql` for each application can be found in
    `IoTa-Installer/resources` and in `<app>/src/main/resources/sql`.

2. Install the web application as explained earlier.
    At this point, the web application will probably fail to properly start.

3. The context file

    Modify the file `$CATALINA_HOME/webapps/<webapp>/META-INF/context.xml` to
    reflect the values for your database (name, login and password).

    Sometimes, it is needed to have a copy of this file as
    `$CATALINA_HOME/conf/localhost/<webapp>.xml`.

    Reload the web application or restart the servlet container.

Do not forget to install the JDBC connector jar file. (For Apache Tomcat and
MySQL, copy `mysql-connector-java.jar` in `$CATALINA_HOME/lib`.)


### ONS

Some applications need an Object Naming Service. NAPTR records are use to find
the URL of the Discovery Service for a given EPC code.

Here is a typical zone file for the product `urn:epc:id:sgtin:1234567.89012`:

    ;;
    $TTL 1d
    
    ;; zone, the vendor Id
    $ORIGIN 7.6.5.4.3.2.1.sgtin.id.ons-peer.com.
    
    @ IN SOA localhost info.example.com ( ; info@example.com
                            2012010101 ; serial version number
                            3h         ; refresh
                            1h         ; retry
                            1d         ; expire
                            1          ; negative cache TTL
                            )
    
    ;; this server’s name
      IN NS ons.example.com.
    
    ; NAPTRs for products
    ; example product
    ;                 order pref flags service    regex
    2.1.0.9.8  IN NAPTR 0     0    "u"   "epc+html" "!^.*$!http://www.example.com/!" .
               IN NAPTR 1     0    "u"   "epc+epcis"   "!^.*$!http://epcis.example.com/epcis/!" .
               IN NAPTR 2     0    "u"   "epc+ided_epcis"   "!^.*$!http://epcis.example.com/eta/!" .
               IN NAPTR 3     0    "u"   "epc+ds"   "!^.*$!http://ds.example.com/ds/services/ESDS_Service!" .
               IN NAPTR 4     0    "u"   "epc+ds"   "!^.*$!http://ds.example.com/dseta/ds/!" .
               IN NAPTR 5     0    "u"   "epc+ided_ds"   "!^.*$!http://ds.example.com/dseta/ided_ds/!" .
    ; first, the HTML web page for product information
    ; then, the EPCIS-repository web service associated to this EPC
    ; then, the identified EPCIS-repository (ETa) web service associated to this EPC
    ; then, the Discovery web service associated to this EPC (WINGS version)
    ; then, the Discovery web service associated to this EPC
    ; finally, the identified Discovery web service associated to this EPC
    ; the order is free


On Debian and Debian-derived systems, you just need to install the `bind9`
package, to create one or more zone file as the cited example and to activate
those zones, that is to add that kind of statement in `named.conf.local`:

    zone "7.6.5.4.3.2.1.sgtin.id.ons-peer.com" {
         type master;
         file "/etc/bind/db.ons.peer.com";
    };


Remember that in order to avoid a recursive open relay DNS, you need to add
these options (in the `options` statement of `named.conf.options`):

    allow-transfer { none; };
    allow-recursion { none; };
    recursion no;


### LDAP

Some applications (YPSilon) need an LDAP server.

From a fonctionnal LDAP server, the script `YPSilon/ldap.sh` or the LDAP module of
the IoTa-Installer adds a schema, a group and the two users superadmin and
anonymous.

On Debian and Debian-derived systems, you just need to install the packages
`slapd` and `ldap-utils`. You have to execute `dpkg-reconfigure slapd` in
order to complete the configuration.

To add index on attributes (like the DN of user certificate used when this DN is
incompatible with the LDAP tree, "aliasdn" by default), you can use the
ldapmodify command with this properties:

    dn: olcDatabase={1}hdb,cn=config
    changetype: modify
    add: olcDbIndex
    olcDbIndex: aliasdn eq

where "olcDatabase={1}hdb" is the used base.


### ActiveMQ

Some applications (ETa-Callback*) need an ActiveMQ JMS broker.

On Debian and Debian-derived systems, you just need to install the package
`activemq`.


### Memory Issues

Due to extensive introspection (e.g. by Hibernate or CXF), and if you want to
install all the web applications on the same server, the JVM “PermGen” memory
needs to be increased. For Apache Tomcat, it can be done with the environment
variable JAVA_OPTS. In POSIX shells, that can be done by a command like the
following one:

    export JAVA_OPTS='-Xms2048m -Xmx4096m -XX:MaxPermSize=512m'

This environment variable needs to be set before starting Apache Tomcat hence
before starting the IoTa installer (as the IoTa installer starts Apache
Tomcat).

This is only necessary if you install all (or most of) the web applications in
the same servlet container.