====== Installazione Tomcat e Mod_JK per GeoServer ======

Installazione su Debian Lenny, con pacchetti **non-free**.

Dal sito **[[http://geoserver.org/|geoserver.org]]** si scarica l'archivio web (**WAR**), questo richiede che Tomcat sia già installato e funzionante.

Un'alternativa sarebbe l'installazione della versione **Unix binary** che in un solo pacchetto fornisce GeoServer e Jetty (Jetty è un server web con Java servlet engine). Ma noi vogliamo usare il server web Apache e Tomcat, quindi dobbiamo installare i pacchetti **apache2**, **tomcat5.5** e il connettore **libapache2-mod-jk**.

===== Installazione di Tomcat e Java =====

In breve: installare i seguenti pacchetti **non-free**:

  * **sun-java6-jdk**
  * **tomcat5.5**
  * **tomcat5.5-admin**
  * **tomcat5.5-webapps**

Si aggiunge la componente **non-free** in **''/etc/apt/sources.list''** e si installa il pacchetto **tomcat5.5**. Il pacchetto installa tramite le dipendenze anche l'ambiente **[[http://gcc.gnu.org/java/|GNU Java]]** (implementazione Java libera).

Per installare Java di SUN (non-free) si installa il pacchetto **sun-java6-jdk** (il solo JRE non è sufficiente per compilare le JSP in classi Java), per scegliere l'implementazione di Java preferita tra le alternative:

<code>
update-alternatives --config java
update-alternatives --config javac
update-alternatives --config javah
update-alternatives --config javadoc
</code>

Controllare eventuali altre alternative in **''/var/lib/dpkg/alternatives/java*''**, ma forse è più efficace rimuovere i pacchetti liberi **gij-4.3**, **ecj** e **gcj-4.3**.

Le directory utilizzate da Debian sono:

^ ''/etc/tomcat5.5''        | ''catalina.policy'', ''server.xml'', ''tomcat-users.xml'', ...  |
^ ''/var/lib/tomcat5.5''    | conf, logs, shared, temp, webapps and work  |
^ ''/usr/share/tomcat5.5''  | bin, common, doc and server  |

Il server http di Tomcat si mette in ascolto sulla porta **TCP 8180** (''%%http://host:8180/%%'', configurazione specifica Debian, generalmente viene utilizzata invece la porta 8080). La configurazione di Tomcat è in **''/etc/tomcat5.5/server.xml''**.

Inoltre Tomcat si mette in ascolto sulla porta **TCP 8009** (per il JK connector, vedi avanti) e sulla porta **TCP 8005** (solo localhost) per accettare il comando di shutdown.

Per semplificare l'amministrazione è possibile installare il pacchetto **tomcat5.5-admin**, che fornisce delle pagine web di amministrazione (per la precisione sono tre webapps) agli indirizzi:

  * **''%%http://host:8180/admin%%''**
  * **''%%http://host:8180/manager/html%%''**
  * **''%%http://host:8180/host-manager%%''**

Per accedere alle webapps //admin// e //manager// bisogna usare un utente abilitato al ruolo di **admin** e **manager** rispettivamente. Login e password predefiniti possono essere cambiati nel file **''/etc/tomcat5.5/tomcat-users.xml''** (riavviare Tomcat dopo la modifica).

Gli utenti predefiniti Debian (//tomcat//, //role1//, //both//) non sono sufficienti ed hanno password da modificare. Ecco un esempio con gli utenti //admin// e //manager//:

<code xml>
<role name="admin"/>
<role name="manager"/>
<user name="admin" password="secret" roles="admin"/>
<user name="manager" password="secret" roles="manager"/>
</code>

Altro pacchetto utile da installare è **tomcat5.5-webapps** che fornisce una pagina iniziale di welcome ed alcune webapps di esempio:

^ Webapp path             ^ Description  ^
| **''/''**                   | Welcome to Tomcat  |
| **''/balancer''**           | Tomcat Simple Load Balancer Example App  |
| **''/jsp-examples''**       | JSP 2.0 Examples  |
| **''/servlets-examples''**  | Servlet 2.4 Examples  |
| **''/tomcat-docs''**        | Tomcat Documentation  |
| **''/webdav''**             | Webdav Content Management  |

==== Configurazione ====

Alcune configurazioni vanno in **''/etc/default/tomcat''**:

<file>
JAVA_HOME=/usr/lib/jvm/java-6-sun
TOMCAT5_SECURITY=yes
</file>

La **''JAVA_HOME''** punta alla directory dove è installato il Java JDK, deve contenere le directory **''bin''** e **''lib''**.

A volte si decide di **disabilitare il [[http://tomcat.apache.org/tomcat-5.5-doc/security-manager-howto.html|Java Security Manager]]** per consentire a qualche webapp di avviarsi senza problemi. Questo va fatto solo se ci fidiamo di tutte le webapps installate, cioè se siamo sicuri che tali applicazioni non tenteranno di eseguire operazioni non lecite.

Operazioni non lecite potrebbero essere: accedere in modo arbitrario al filesystem, interferire con i processi in esecuzione sul server, accedere in modo arbitrario ai servizi di rete, ecc. Dobbiamo fidarci che le **webapps** non solo siano **scritte senza intenti malevoli**, ma che siano anche scritte **tenendo in considerazione la sicurezza** del sistema.

Se il Java Security Manager è attivo, qasi sicuramente dovremmo dichiarare le azioni consentite alle varie webapps scrivendo regole opportune ad esempio in **''/etc/tomcat5.5/policy.d/50user.policy''**. Non si dovrebbe editare direttamente il file ''/etc/tomcat5.5/catalina.policy'', che in Debian viene generato automaticamente.

===== Installazione di Mod_JK =====

Per utilizzare Apache invece del server http di Tomcat (che Debian mette sulla porta 8180) si installa il pacchetto **libapache2-mod-jk**. Mod_JK dialoga con Tomcat grazie al **connettore Coyote/JK AJP 1.3** abilitato sulla **porta 8009** (configurazione Tomcat di Debian).

La configurazione del connettore si trova in **''/etc/libapache2-mod-jk/workers.properties''**, ma non viene usata per default, bisogna indicarla nella configurazione di Apache tramite la direttiva **''JkWorkersFile''**.

Tra le impostazioni fondamentali troviamo **il nome** del connettore, **il tipo** e **la porta** su cui connettersi a Tomcat:

<file>
worker.list=ajp13_worker
worker.ajp13_worker.port=8009
worker.ajp13_worker.host=localhost
worker.ajp13_worker.type=ajp13
</file>

Nella configurazione predefinita il connettore logga in **''/var/log/apache2/mod_jk.log''**.

Per reindirizzare le richieste ricevute da Apache a Tomcat - passando per Mod_JK - è sufficiente aggiungere alcune direttive alla configurazione di Apache. Ad esempio:

<file>
<IfModule mod_jk.c>
    JkWorkersFile /etc/libapache2-mod-jk/workers.properties
    JkLogLevel debug

    JkMount /admin/* ajp13_worker
    Alias /admin /usr/share/tomcat5.5/server/webapps/admin/

    JkMount /manager/* ajp13_worker
    Alias /manager /usr/share/tomcat5.5/server/webapps/manager/

    JkMount /geoserver/* ajp13_worker
    Alias /geoserver /var/lib/tomcat5.5/webapps/geoserver/
</IfModule>
</file>

Attenzione che la direttiva **''JkWorkersFile''** è necessaria, ma non è consentita all'interno di un ''VirtualHost'', mentre le direttive **''JkMount''** e **''Alias''** sono proprie del ''VirtualHost'' (anzi **devono** stare nella sezione VirtualHost se i VirtualHost sono attivi).

===== Deploy del WAR GeoServer =====

È sufficiente copiare il file **''geoserver.war''** nella directory webapps di Tomcat: **''/var/lib/tomcat5.5/webapps/''**. Tomcat provvede automaticamente a scompattare l'archivio.

==== Java Security Manager ====

La webapp **geoserver** non si avvia con l'impostazione predefinita **''TOMCAT5_SECURITY=yes''** in ''/etc/default/tomcat5.5''.

Nella pagina web del //manager// l'applicazione geoserver risulta installata, ma lo stato di **running** è **false**. Cliccando su **start** si ottiene un errore i cui dettagli sono in **''/var/log/tomcat5.5/catalina.*.log''** (Catalina è il nome del servlet container di Tomcat).

Disabilitando il Java Security Manager, geoserver si avvia senza problemi, vedi sopra le implicazioni sulla sicurezza.

FIXME Non funziona con il Security Manager attivo! Il primo errore:

<code>
Caused by: java.security.AccessControlException: access denied (java.io.FilePermission /var/lib/tomcat5.5/webapps/geoserver/W
EB-INF/classes/logging.properties read)
</code>

Si risolve aggiungendo alcune policy ''/etc/tomcat5.5/policy.d/60geoserver.policy'':

<file>
// The permissions granted to Geoserver
grant codebase "file:/var/lib/tomcat5.5/webapps/geoserver/-" {
        permission java.io.FilePermission "/var/lib/tomcat5.5/webapps/geoserver/data/-", "read,write,delete";
        permission java.util.PropertyPermission "*", "read,write";
        permission java.util.logging.LoggingPermission  "control";
        permission java.lang.RuntimePermission "getClassLoader";
        permission java.lang.RuntimePermission "preferences";
        permission java.lang.RuntimePermission "shutdownHooks";
        permission java.lang.reflect.ReflectPermission "suppressAccessChecks";
};

grant codeBase "file:${catalina.home}/bin/tomcat-juli.jar" {
        permission java.io.FilePermission "/var/lib/tomcat5.5/webapps/geoserver/WEB-INF/classes/logging.properties", "read";
};
</file>

ma non basta! Si continuano ad avere errori:

<code>
INFO: Deploying web application archive geoserver.war
Jul 11, 2009 3:22:40 PM org.apache.catalina.core.StandardContext start
SEVERE: Error listenerStart
Jul 11, 2009 3:22:40 PM org.apache.catalina.core.StandardContext start
SEVERE: Context [/geoserver] startup failed due to previous errors
</code>

Inoltre pare ci siano problemi con la libreria GDAL:

<code>
Jul 11, 2009 12:40:15 PM it.geosolutions.imageio.gdalframework.GDALUtilities loadGDAL
WARNING: Native library load failed.java.lang.UnsatisfiedLinkError: no gdaljni in java.library.path
</code>

==== Supporto Oracle ====

Copiare nella directory **''/var/lib/tomcat5.5/webapps/geoserver/WEB-INF/lib''** i seguenti archivi jar e riavviare la webapp:

^ gt-oracle-spatial-2.5.6.jar   | Plugin Oracle  |
^ gt-jdbc-core-2.5.6-tests.jar  | Plugin Oracle NG  |
^ gt-jdbc-core-2.5.6.jar        | Plugin Oracle NG  |
^ gt-jdbc-oracle-2.5.6.jar      | Plugin Oracle NG  |
^ ojdbc14.jar                   | JDBC Driver per Oracle 10g Release 10.2.0.4  |

I plugin GeoServer sono stati scaricati dalla stessa [[http://geoserver.org/display/GEOS/Stable|pagina di download di GeoServer]] (devono corrispondere alla versione di GeoServer installata).

Il driver per Oracle (**''ojdbc14.jar''**) è contenuto anche negli archivi dei plugin, ma lo si può scaricare direttamente dal [[http://otn.oracle.com/software/tech/java/sqlj_jdbc/index.html|sito di Oracle]], esistono versioni differenti per differenti versioni di Oracle e per differenti versioni di JDK.

Se la versione di JDK è minore di 1.4, si deve utilizzare il driver distribuito nell'archivio **''classes12.jar''**. Per le JDK versione 1.5 e 1.6 si dovrebbero utilizzare **''ojdbc5.jar''** e **''ojdbc6.jar''** rispettivamente, tali archivi sono distribuiti anche con il driver //OCI Oracle Instant Client//.

Formati DataStore Oracle supportati:

^ Oracle            | FIXME Problema con gli schemi (vedi avanti).\\ Effettua una [[http://docs.geoserver.org/1.7.x/user/data/oracle.html|connessione Oracle]] standard, tramite l'uso del solo driver [[wp>JDBC|JDBC]]. Viene chiamato anche //Thin driver//.  |
^ Oracle (OCI)      | FIXME Problema con gli schemi (vedi avanti).\\ In questo caso il driver JDBC passa la connessione al driver OCI (Oracle Client Interface) che deve essere installato sulla stessa macchina. Questo driver, detto anche //Thick driver//, dovrebbe avere performance migliori rispetto alla connessione con Thin driver, ma l'overhead del passaggio da Java a C potrebbe invece peggiorarle.\\ JDBC cerca la libreria OCI nella **''java.library.path''**. Ad esempio **''ojdbc14.jar''** cerca **''libocijdbc10.so''** mentre **''ojdbc6.jar''** cerca **''libocijdbc11.so''**.  |
^ Oracle NG         | FIXME Problema con i campi BLOB (vedi avanti).\\ Il plugin [[http://docs.geoserver.org/1.7.x/user/data/oracleng.html|Oracle NG]] si basa sul driver [[wp>JDBC|JDBC]]. Funziona!\\ **ATTENZIONE** il nome dello schema è //case sensitive//, di solito tutto MAIUSCOLO!  |
^ Oracle NG (JNDI)  | Usa la tecnologia //[[http://docs.geoserver.org/1.7.x/user/data/jndi-connection-pools.html|Java Naming and Directory Interface]]//: l'amministratore configura una o più connessioni al database e le webapp utilizzano queste connessioni per nome, senza conoscerne i dettagli.  |

Vedere anche le pagine [[http://www.orafaq.com/wiki/JDBC|Oracle JDBC]] e [[http://www.stanford.edu/dept/itss/docs/oracle/10g/java.101/b10979/getsta.htm|JDBC Developer's Guide and Reference]] (in inglese) e [[http://www.xenialab.it/meo/web/white/oracle/ora_jdbc3.htm|Oracle JDBC]] (in italiano).

=== Impostare la java.library.path ===

Per impostare la **''java.library.path''** in Debian si può intervenire sia sulla **''JAVA_OPTS''** (passando un parametro **''-D''** a Java) sia impostando **''LD_LIBRARY_PATH''** per il processo Tomcat.

In entrambi i casi si modifica **''/etc/default/tomcat5.5''**. Se si imposta ''JAVA_OPTS'', se ne può approfittare anche per assegnare maggire memoria all'heap:

<file>
JAVA_OPTS="-Djava.awt.headless=true -Xmx512M -Djava.library.path=/usr/lib/oracle/11.1/client/lib"
</file>

<file>
export ORACLE_HOME=/usr/lib/oracle/11.1/client
export LD_LIBRARY_PATH=$ORACLE_HOME/lib
</file>

=== Configurazione DataStore Oracle ===

Parametri di **configurazione DataStore Oracle**, esempi:

{{.geoserver:geoserver-datastore-oracle.png?60|Oracle}}
{{.geoserver:geoserver-datastore-oracle-oci.png?60|Oracle (OCI)}}
{{.geoserver:geoserver-datastore-oracle-ng.png?60|Oracle NG}}

==== Installazione JAI ====

Andrea Aime suggerisce - per migliorare le performance - di installare il supporto nativo (libreria **''libmlib_jai.so''**) per le librerie **JAI** e **JAI Image I/O**. Vedere le [[http://geoserver.org/display/GEOSDOC/Dealing+with+native+JAI|istruzioni relative]].

==== Configurazione ====

=== Login/Password ===

Il login predefinito di GeoServer è **user=admin** con  **password=geoserver**. Per cambiarlo si modifica il file **''geoserver/data/security/users.properties''**.

=== WFS boundedBy ===

Per il servizio WFS conviene **attivare l'opzione //Generate feature bounds//** (//Config//, //WFS//, //Contents//), in questo modo viene generato il tag **''%%boundedBy%%''** per ogni **''FeatureCollection''** e per ogni **''featureMember''** nelle risposte alle richieste **''GetFeature''**.

Senza questa impostazione lo strumento **//zoom to layer//** di QGIS funziona.

==== Broblemi ====

=== Connessione con plugin Oracle ===

[[http://sourceforge.net/mailarchive/message.php?msg_name=CB3F2C7554304FF294BD303D920A7871%40YARRACON|Bug report]].\\
La connessione al DataStore pare funzionare, infatti durante la creazione di un nuovo FeatureTypes si ottiene il listing delle tabelle disponibili. Ma tutte le volte che viene eseguita una interrogazione si ottiene l'errore:

<code>
* class org.geotools.data.DataSourceException: Could not count Request All Features
* class java.sql.SQLSyntaxErrorException: ORA-00942: table or view does not exist
  ORA-06512: at "MDSYS.SDO_TUNE", line 881
</code>

Pare che la SELECT venga costruita senza usare lo schema; nella risposta ad una richiesta WFS si legge l'errore:

<code>
Error Performing SQL query: SELECT "OBJECTID", "FK_STRADE", "FK_COMUNI_BELF",
"TOPONIMO_STRADA", "GEOMETRY" FROM "AGGR_TRATTISTRADALI"
ORA-00942: table or view does not exist
</code>

=== Campo blob in tabella Oracle ===

[[http://jira.codehaus.org/browse/GEOS-3099|Bug report]].\\
Se la teabella Oracle contiene un campo blob, la richiesta WFS **''DescribeFeatureType''** fallisce con un errore:

<code>
<ServiceException>
   java.lang.NullPointerException: Could not find a type for property:
   SE_ANNO_CAD_DATA of type: java.lang.Object
   Could not find a type for property: SE_ANNO_CAD_DATA of type: java.lang.Object
</ServiceException>
</code>

=== QGIS e layer WFS con namespace ===

[[http://trac.osgeo.org/qgis/ticket/1599|Bug report]].\\
La richiesta WFS **''DescribeFeatureType''** su un layer che non sta nel namespace predefinito (**topp**), fallisce perché GQIS invece del parametro **''TYPENAME=nspace:layer''** passa il parametro **''TYPENAME=layer''**.

===== Web links =====

  * [[http://www.crazysquirrel.com/computing/debian/servers/debian-tomcat-package.jspx|Installing the Debian Tomcat Package]]
  * [[http://docs.geoserver.org/|GeoServer Documentation]]