Deployment

This chapter covers the following topics:

Removing ready-made sites

Intranet is a ready-made site that you can access by the URL: /portal/intranet. If you want to remove it from the eXo Platform package, consider 2 cases below:

First case - Your package is fresh so data is empty

Remove the following files:

  • $PLATFORM_TOMCAT_HOME/webapps/acme-intranet.war

  • $PLATFORM_TOMCAT_HOME/webapps/acme-intranet-portlet.war

  • $PLATFORM_TOMCAT_HOME/lib/platform-sample-acme-intranet-config-*.jar

Second case - Data has been created

Warning

You need to be clear what you will delete, so review carefully before deletion.

To clean the data entirely, do the following steps:

  1. Stop the server if it is running.

  2. Remove the files as described above.

  3. Remove associated data. If you did not change the default data configuration, just need to remove $PLATFORM_TOMCAT_HOME/gatein/data/.

  4. Restart your server.

Setting up an HTTP frontend

It may be necessary to use an HTTP server as a front-end (aka a reverse-proxy) for your eXo Platform application server to allow :

  • Accessing more than one application server on the same host;

  • Accessing these app servers with the separate DNS names, without adding a port to the URL;

  • Serving maintenance pages if the server is not available.

  • Instrumenting your http request (for Single Sign on authentication for example)

  • Caching and/or load-balancing

  • Improving security with server isolation

This diagram represents a standard deployment with a reverse proxy We recommand to use the http protocol as communication protocol between the HTTP proxy and the eXo Platform server as it’s simpler to configure than the AJP protocol for the same performances.

Setting up Apache front-end

Basic configuration for Apache

To allow Apache to act as a reverse proxy, you first need to activate some modules :

  • mod_proxy

  • mod_proxy_http

  • Optional mod_proxy_wstunnel to use websocket for the notification websockets

This can be acheived with the following command : a2enmod proxy proxy_http proxy_wstunnel

Next, declare a new virtual host to access you eXo Platform instance :

Note

You can find more information on how to configure apache vhosts on here.

<VirtualHost *:80>

        ServerName my.server.name # <--- change here

        ServerAdmin [email protected] # <--- change here

        # don't loose time with IP address lookups
        HostnameLookups Off
        # needed for named virtual hosts
        UseCanonicalName Off
        # configures the footer on server-generated documents
        ServerSignature Off

        ProxyRequests           Off
        ProxyPreserveHost       On
        ProxyVia                On

        # Notifications via web socket, must be declared before the general ProxyPass definition
        <IfModule proxy_wstunnel_module>
                ProxyPass           /cometd    ws://127.0.0.1:8080/cometd max=100 acquire=5000 retry=5 disablereuse=on flushpackets=on # <--- change here and adapt the options to your load
        </IfModule>

        ProxyPass               /          http://127.0.0.1:8080/ acquire=1000 retry=30 max=100 # <--- change here and adapt the options to your load
        ProxyPassReverse        /          http://127.0.0.1:8080/  # <--- change here

        #####################
        # Log configuration
        #####################
        ErrorLog        ${APACHE_LOG_DIR}/my.server.name-error.log # <--- change here
        CustomLog       ${APACHE_LOG_DIR}/my.server.name-access.log log_with_durations # <--- change here

</VirtualHost>

Note

We are assuming the eXo Platform server is reachable at the ip 127.0.0.1 on port 8080. You have to adapt the configuration according to your installation.

Warning

Due to a bug in Apache Server prior version 2.4.13, an incorrect websocket configuration can impact the standard HTTP navigation. If you randomly have blank pages or portlet errors, please check the websocket tunnels are correctly working

This example use a log definition called log_with_durations. This is a customization of the default combined apache log format with the request durations. It’s totally optional, if you don’t want to override the log configuration, use the combined format You can add it to your Apache installation by adding the following content in your configuration :

LogFormat "%h %l %u %t \"%r\" %>s %O \"%{Referer}i\" \"%{User-Agent}i\" %T" log_with_durations

Note

It is also recommanded to enable the apache status page to be able to monitor the apache behavior. More info are available here

Setting up an Nginx front-end

Basic configuration for Nginx

Note

You can find the detailled documentation on the nginx configuration as reverse proxy here

Nginx supports reverse-proxy instructions without the need to add modules.

This is an example of a nginx server configuration acting as a reverse proxy of a eXo Platform back-end :

server {
  listen 80 default_server;
  server_name my.server.name;

  # TODO Adapt this value to your needs
  client_max_body_size 250m;

  location / {
        proxy_pass http://127.0.0.1:8080;
        # Pass the client informations the the backend
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header Host $host;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
  }
  # Websocket for notifications
  location /cometd/cometd {
        proxy_pass http://127.0.0.1:8080;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header Host $host;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
  }

  access_log   /my/path/my.server.name-access.log log_with_durations;
  error_log    /my/path/my.server.name-error.log;

}

Note

We are assuming the eXo Platform server is reachable at the ip 127.0.0.1 on port 8080. You have to adapt the configuration according to your installation.

This example uses a log definition called log_with_durations. This is a customization of the default combined log format with the request durations. It’s totaly optional, if you don’t want to override the log configuration, use the combined format You can add it to your nginx configuration by adding the following line in your host section :

log_format combined_with_durations '$remote_addr - $remote_user [$time_local] '
        '"$request" $status $body_bytes_sent '
        '"$http_referer" "$http_user_agent" $request_time';

It’s also good to add this option to limit the server exposition:

server_tokens off;

Note

It is also recommanded to enable the apache status page to be able to monitor the apache behavior. More info are available here

Setting up a Tomcat for a front-end

Base configuration for Tomcat

The tomcat configuration must be adapted to be used behind a http frontend.

  • An HTTP Connectormust be declares and specifically configured to reply to the reverse proxy. In the server.xml file, add or edit a HTTP connecter :

<Connector address="127.0.0.1" scheme="http" secure="false" proxyName="community-qa.exoplatform.com" port="8080" protocol="org.apache.coyote.http11.Http11NioProtocol"
  enableLookups="false" redirectPort="8443" bindOnInit="false"
  connectionTimeout="20000" disableUploadTimeout="true"
  URIEncoding="UTF-8"
  compression="off" compressionMinSize="2048"
  noCompressionUserAgents=".*MSIE 6.*" compressableMimeType="text/html,text/xml,text/plain,text/css,text/javascript" />

Note

The complete documentation of the Tomcat connector can be found here

This is a standard connector configuration with the important paramters for a reverse proxy context :

scheme

If your reverse proxy acts as a ssl termination, specify https, specify https otherwise

secure

If your reverse proxy acts as a ssl termination, specify true, specify false otherwise

proxyName

The name of eXo Platform instance as viewed by the user

bindOnInit

Must be set to false to avoid the connector to be started before eXo Platform was completely deployed and ready to respond.

  • A valve must be added to retreive the original user information like ip, scheme instead of the reverse-proxy properties. In the section Engine/Host of the server.xml, add this definition:

    <Valve className="org.apache.catalina.valves.RemoteIpValve" internalProxies="127.0.0.1" remoteIpHeader="x-forwarded-for" proxiesHeader="x-forwarded-by" protocolHeader="x-forwarded-proto" />

Parameters

internalProxies

Declare your reverse proxy ips. IP range accepted

*Header

The name of the headers your reverse proxy will set. The values on the example are the default names used by most of the reverse proxies. It’s true for Apache , it must be explicitely specified for nginx.

Note

The complete documentation of the RemoteIpHeader is available here

Configuring HTTP session timeout

The session timeout defines the validation period of a session. In the portal environment, such as eXo Platform, it is highly recommended that all web applications have the same session timeout value.

The session timeout is configurable individually for each web application in the web.xml file:

<session-config>
    <session-timeout>30</session-timeout>
</session-config>

The value is in minute.

In Tomcat, you can set session timeout globally by modifying the conf/web.xml file.