root/INSTALL @ 675e977d
2e0a7cb1 | Sylvain L. Sauvage | Building and Installing
|
|
=======================
|
|||
Building
|
|||
--------
|
|||
IoTa uses Apache Maven for build automation (http://maven.apache.org).
|
|||
96454bcd | Sylvain L. Sauvage | A convenience building script is provided: make-all.sh.
|
|
2e0a7cb1 | Sylvain L. Sauvage | 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.)
|
|||
96454bcd | Sylvain L. Sauvage | **The IoTa-Installer can help you to install and configure all the servers and
|
|
databases.**
|
|||
2e0a7cb1 | Sylvain L. Sauvage | ||
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
|
|||
96454bcd | Sylvain L. Sauvage | Use the provided script to start the application.
|
|
2e0a7cb1 | Sylvain L. Sauvage | ||
19b58bab | Rémy Ménard | ### 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"/>
|
|||
2e0a7cb1 | Sylvain L. Sauvage | ### 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
|
|||
96454bcd | Sylvain L. Sauvage | $ORIGIN 7.6.5.4.3.2.1.sgtin.id.ons-peer.com.
|
|
2e0a7cb1 | Sylvain L. Sauvage | ||
@ 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
|
|||
96454bcd | Sylvain L. Sauvage | IN NS ons.example.com.
|
|
2e0a7cb1 | Sylvain L. Sauvage | ||
; 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/!" .
|
|||
96454bcd | Sylvain L. Sauvage | 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/!" .
|
|||
2e0a7cb1 | Sylvain L. Sauvage | ; first, the HTML web page for product information
|
|
96454bcd | Sylvain L. Sauvage | ; 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
|
|||
2e0a7cb1 | Sylvain L. Sauvage | ||
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`:
|
|||
96454bcd | Sylvain L. Sauvage | zone "7.6.5.4.3.2.1.sgtin.id.ons-peer.com" {
|
|
2e0a7cb1 | Sylvain L. Sauvage | 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`):
|
|||
96454bcd | Sylvain L. Sauvage | allow-transfer { none; };
|
|
allow-recursion { none; };
|
|||
2e0a7cb1 | Sylvain L. Sauvage | recursion no;
|
|
### LDAP
|
|||
bf9c3717 | Rémy Ménard | Some applications (YPSilon) need an LDAP server.
|
|
2e0a7cb1 | Sylvain L. Sauvage | ||
bf9c3717 | Rémy Ménard | From a fonctionnal LDAP server, the script `YPSilon/ldap.sh` or the LDAP module of
|
|
2e0a7cb1 | Sylvain L. Sauvage | 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.
|
|||
96454bcd | Sylvain L. Sauvage | ||
8fd1d584 | Rémy Ménard | 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.
|
|||
96454bcd | Sylvain L. Sauvage | ||
### 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.
|