|
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.
|