Skip to content
This repository has been archived by the owner on Jul 2, 2018. It is now read-only.

Server setup

Jump to bottom
Natasa Bulatovic edited this page Jul 26, 2016 · 8 revisions

Operating system

As a Java software, imeji works on all operating system where Java is installed. Nevertheless, we recommend using http://www.opensuse.org (or SUSE Linux Enterprise Server) which is used for the development and testing of imeji.

Install Java Development Kit

imeji supports Java 8, to set it up:

_Notes: _ * Java 6 is not supported anymore from imeji 2.0.0.0 version, Java 7 is not supported anymore from imeji 3.4.0.0 version. * We have a report that OpenJDK seems to be working just fine as well, see the installation instructions and follow the instructions for JDK8.

Install Tomcat

imeji runs with Tomcat 7.x:

(Optional) Install Elasticsearch

imeji uses Elasticsearch to power its search. Even though Imeji can be installed standalone (it will start its own Elasticsearch node), we strongly recommend to install an Elasticsearch cluster separately for productive use.

  1. Download Elasticsearch 2.0.1
  2. Unpack it on your Elasticsearch server
  3. Edit /elasticsearch_home/config/elasticsearch.yml: Set property cluster.name: yourcluster same as in imeji.properties elastic.cluster.name
  4. (if Elasticsearch is installed separately): install ICU Analysis plugin
  5. Start Elasticsearch with: /elasticsearch_home/bin/elasticsearch -d (-d: to run process as daemon)

Installation snippet

Example for installing elasticsearch 2.0.1. Please, adapt it to your installation

wget https://download.elasticsearch.org/elasticsearch/release/org/elasticsearch/distribution/tar/elasticsearch/2.0.1/elasticsearch-2.0.1.tar.gz
tar xfvz elasticsearch-2.0.1.tar.gz
mv elasticsearch-2.0.1 /data/
cd /data 
useradd elastic 
chown -R elastic: elasticsearch-2.0.1/ 
export ES_HEAP_SIZE="2g" 
su elastic 
cd elasticsearch-2.0.1/config/ 
vi elasticsearch.yml // Edit the file as you need 
/data/elasticsearch-2.0.1/bin/plugin install analysis-icu 
/data/elasticsearch-2.0.1/bin/elasticsearch -d

We recommend following configurations in imeji.properties:

  • if imeji is running standalone (i.e. without separate Elasticsearch cluster):
   elastic.cluster.name= clustername
   elastic.cluster.local=true
   elastic.cluster.data=true
   elastic.cluster.home= /data/imeji/elastic
   elastic.analyser = standard
  • (strongly recommended) if you installed your own Elasticsearch cluster
    
   elastic.cluster.name= clustername
   elastic.cluster.local=false
   elastic.cluster.data=false
   elastic.cluster.home= /data/imeji/elastic
   # If ICU Analysis plugin is installed
   elastic.analyser = ducet_sort

For better performance, Elasticsearch cluster might be installed on a separate server than imeji server. 

## (Optional) Install Apache Server

For special http settings, such as changing the default port configuration, URL customization or https settings, you may want to download and install the [Apache HTTP server](http://httpd.apache.org/). Recommended configuration: 
    
    
    # Add following lines at the end of your proxypass rules. Change the port, if needed.
    ProxyPass /imeji http://localhost:8080/imeji
    ProxyPassReverse /imeji http://localhost:8080/imeji
    ProxyPass / http://localhost:8080/imeji
    ProxyPassReverse / http://localhost:8080/imeji

  * Important: following modules must be loaded in Apache Server 
    * proxy_module
    * proxy_http_module

## (Optional) Install ImageMagick

imeji uses  (from imeji version 1.3.0.0) to support more various formats e.g. images, videos and audio formats. Therefore we strongly recommend to install it: 

  * Follow the installation instructions according to your operating system
  * Set the ImageMagick properties in [imeji.properties](https://github.com/imeji-community/imeji/blob/develop/src/main/resources/imeji.properties)

## (Optional) CoNE service - install your own or use existing CoNE service

The Max Planck Digital Library (MPDL)  provides a [Control of Named Entities Service](http://pubman.mpdl.mpg.de/cone/),  which is a home to several controlled vocabularies, publicly available for reuse. You may use these vocabularies during the definition of your metadata fields. During item editing, values will be autosuggested from the selected vocabulary and selected value will be set as a metadata value. To **install your own CoNE service** on your server, see  To **use the existing MPDL CoNE service** edit the following property files as follows: 

  * In [imeji.properties](https://github.com/imeji-community/imeji/blob/develop/src/main/resources/imeji.properties) :

   cone.isos639_1.all=http://pubman.mpdl.mpg.de/cone/iso639-1/all



    

  • all properties in vocabularies.properties (according to what you need, an example for the MPDL CoNE service provided below)
    • 



cone_authors=http://pubman.mpdl.mpg.de/cone/persons/query?format=json&n=10&m=full&q=
cone_CreativeCommons_licenses=http://api.creativecommons.org/rest/1.5/simple/chooser?locale=
cone_journals=http://pubman.mpdl.mpg.de/cone/journals/query?format=json&n=10&m=full&q=` `cone_Languages_(iso639-3)=http://pubman.mpdl.mpg.de/cone/iso639-3/query?format=json&n=10&m=full&q=
cone_IANA_Mimetypes=http://pubman.mpdl.mpg.de/cone/mimetypes/query?format=json&n=10&m=full&q=
cone_DDC_Subjects=http://pubman.mpdl.mpg.de/cone/mpipks/query?format=json&n=10&m=full&q=
google_geo_api=https://maps.googleapis.com/maps/api/geocode/json?sensor=false&address=



To use other existing CoNE service installation, just change the base URL (i.e. http://pubman.mpdl.mpg.de/cone to the appropriate value of the CoNE service)


(Optional) Digilib


If you want to use Digilib (from imeji version 1.3.0.0), follow the installation at the imeji Digilib page.


Performance tuning


Hardware


    

  • imeji performance is widely influenced (more than any other hardware component) by the amount of RAM installed. The minimum needed is 3 GB, but we recommend 16 GB for good scalability and a 64-bits system.
    • 



Java Virtual Machine settings


    

  • with 16 GB RAM and more: -Xms4096m -Xmx4096m -XX:MaxPermSize=512m -Djava.awt.headless=true
    • 

  • with 8 GB RAM : -Xms2048m -Xmx2048m -XX:MaxPermSize=256m -Djava.awt.headless=true
    • 

  • with 4 GB RAM : -Xms1024m -Xmx1024m -XX:MaxPermSize=256m -Djava.awt.headless=true
You can specify these parameters in:
    • 

  • JAVA_OPTS, or
    • 

  • CATALINA_OPTS (if using Tomcat), or
    • 

  • in setenv.sh (if using Tomcat) (recommended)
    • 



Page Compression


    

  • 

    We recommend to enable compression of html pages.This can be done via:
    

      

    • Tomcat: edit the server.xml file with:
      • 

    

    <Connector URIEncoding="UTF-8" connectionTimeout="20000" port="8080"
protocol="HTTP/1.1" redirectPort="8443"
compression="on"
compressableMimeType="text/html,text/xml,text/plain,text/css,
application/x-javascript,application/xml,application/javascript,application/json,application/xhtml+xml"/>
    


    • 



Server Encoding


Please check that you server is using UTF-8 encoding. This ensure correct behavior with special characters:


    

  • 

    Tomcat: edit server.xml with
    

    `<Connector URIEncoding="UTF-8"/>`

    

    • 

  • 

    JBoss: edit standalone.xml with:
    

    • 



<system-properties> <property name="org.apache.catalina.connector.URI_ENCODING" value="UTF-8"/> <property name="org.apache.catalina.connector.USE_BODY_ENCODING_FOR_QUERY_STRING" value="true"/> </system-properties>


Tomcat connector


    

  • Choose best connector according to your priorities (see below requirement Connectors in preference order)
    • 







Stability
BIO
NIO/APR






SSL
APR
NIO  BIO




Low concurrency High concurrency
BIO
APR  NIO




No Keep-Alive High concurrency
BIO
APR  NIO




Keep-Alive
APR
NIO  BIO






If you send a request to tomcat then with all of the connectors you will use tomcat thread to process that request
BIO is Blocking IO Connectors and NIO and APR are Non-Blocking IO Connectors.


BIO means if you use http with keep-alive parameter then you will continue to use that thread in order to maintain keep-alive connection while with Non-Blocking IO Connectors you don’t need to use thread to maintain keep-alive requests, so you can make efficient use of threads here


Misc


Install imeji on Jetty (not tested on versions since 3.X)


Since several files have to be customized first, imeji does not work out of the box as a .war-file in a Jetty 9 server. Here are some instructions which should help to set up a working environment based on the most recent imeji snapshot from GitHub. This setup was tested on a machine running a 64-bit Linux system (Debian Squeeze).


Prerequisites


    

  • Download and install the Jetty 9 server
    • 

  • Install Maven 3.x
    • 



Build imeji snapshot


Check out the sources, for example in /usr/local/src


sudo git clone https://github.com/imeji-community/imeji.git



This will produce a subdirectory "imeji" containing a "pom.xml" file. CD into the "imeji" subdir and do


sudo mvn package



This will download all libraries and build the entire application plus a war file (which we don't use).


Properties files


Create the properties files as described here: https://github.com/imeji-community/imeji/wiki/Properties. The files will be picked up automatically, if you put them in /resources. Remember that a file named "vocabulary.properties" must also exist in this directory, even if you don't want to use vocabularies.


Web context


Create a soft link to your Imeji snapshot build directory:


sudo ln -s /usr/local/src/imeji/target/imeji-1.3.0.1-SNAPSHOT /usr/local/imeji



Put a file named "imeji.xml" in /webapps. Set "contextPath" to the desired URL path and "resourceBase" to the softlink. The content should look like this:


< ?xml version="1.0"> 
< !DOCTYPE Configure PUBLIC "-//Jetty//Configure//EN" "http://www.eclipse.org/jetty/configure.dtd"> 
< Configure class="org.eclipse.jetty.webapp.WebAppContext"> 
  < Set name="contextPath"> /imeji</Set> 
  < Set name="resourceBase"> /usr/local/imeji</Set> 
  < Set name="defaultsDescriptor"> <SystemProperty name="jetty.home" default="."/> /etc/webdefault.xml</Set> 
< /Configure> 



Logging


Make sure that the user account under which Jetty is run has write privilege in Jetty's log directory /logs. Edit the file "WEB-INF/classes/log4j.xml" in your Imeji snapshot directory as follows, replacing the value of the "File" parameter:


< appender name="FILE" class="org.apache.log4j.DailyRollingFileAppender"> 
	< param name="File" value="${jetty.home}/logs/imeji.log" / > 



Add logging for digilib:


  < appender name="log" class="org.apache.log4j.FileAppender"> 
    < param name="File" value="${jetty.home}/logs/imeji-digilib-log.txt"/> 
    < param name="Append" value="true"/> 
    < layout class="org.apache.log4j.PatternLayout"> 
      < param name="ConversionPattern" value="%d [%t] %p - %m%n"/> 
    < /layout> 
  < /appender> 

  < appender name="account" class="org.apache.log4j.FileAppender"> 
    < param name="File" value="${jetty.home}/logs/imeji-digilib-access-log.txt"/> 
    < param name="Append" value="true"/> 
    < layout class="org.apache.log4j.PatternLayout"> 
      < param name="ConversionPattern" value="%d [%t] %p - %m%n"/> 
    < /layout> 
  < /appender> 

  < logger name="account.request"> 
    < level value ="debug"/> 
    < appender-ref ref="account"/> 
  < /logger>  



Add this line to the element of log4j.xml:


   < appender-ref ref="log"/> 



imeji storage configuration


Create directories for Imeji where it can store data. Make sure that the user account under which Jetty is run has write privilege for both. Remember that the last element of the storage path must have the name "files". Set the paths in "imeji.properties" like so:


#Path to Jena's TDB database (RDF storage)
imeji.tdb.path = /var/local/imeji/tdb/

#Path to imeji storage (where the files are stored) (for windows use separator: \\) 
# Note: If you use digilib, the path must end with /files/ !
imeji.storage.path=/var/local/imeji/files/



Digilib configuration


Make sure that the user account under which Jetty is run has write privilege for the file "WEB_INF/digilib-config-xml" in your Imeji snapshot directory. Copy this file to somewhere else, for example to /usr/local/src. Reference the copied file in your imeji.properties file like so:


digilib.configuration.path = /usr/local/src/digilib-config.xml



Edit the copied file and set the desired config parameters for Digilib. Pay attention to the parameter "basedir-list". It must point to the parent directory of the one given in the property "imeji.storage.path" (without the final /files/ part).


Troubleshooting Jetty issues


If the /imeji context does not start and you get an exception in the log saying


:'''could not find Factory: javax.faces.context.FacesContextFactory'''



(explanation [http://stackoverflow.com/questions/5973664/could-not-find-factory-javax-faces-context-facescontextfactory-using-embedded here]) add the following lines to /WEB-INF/web.xml:


< listener> 
   < listener-class> com.sun.faces.config.ConfigureListener< / listener-class> 
< / listener>      



If you get an exception in the log saying


:'''java.lang.illegalstateexception zip file closed'''



edit the following lines in /etc/webdefault.xml, setting "gzip" to false: (explanation [http://stackoverflow.com/questions/19123887/jetty-java-lang-illegalstateexception-zip-file-closed here])


< init-param> 
  < param-name> gzip</ param-name> 
  < param-value> false</ param-value> 
< / init-param>
Clone this wiki locally