Delivery Configuration

Software Requirements

For Sophora web applications, the minimum software requirements are:

• Java 11
• Apache Http Server 2.4
• Apache Tomcat 7 (we strongly recommend Apache Tomcat 9, because version 7 and 8 are end of life)

Notes on Tomcat 7

Tomcat 7 enforces naming restrictions on identifiers in JSP-Templates. The Expression Language 2.2 Specification states in chapter 1.19, that an identifier is constrained to be a Java identifier. Amongst others, keywords such as "this", "for", and "class" must not be used as identifiers. Older versions of Tomcat did not enforce this, and in older releases of Sophora, a variable named "this" was used to reference the content map of the current document. JSP templates using any of the reserved keywords as identifiers will not run on Tomcat 7.

There are two options for migrating from Tomcat 6 to Tomcat 7:

1. Disable the identifier check in Tomcat 7 using the Tomcat system property org.apache.el.parser.SKIP_IDENTIFIER_CHECK.
2. Ensure that your templates don't use reserved keywords as identifiers. In Sophora JSP templates, the content map for the current document is now referenced using the variables "content" (old content map implementation) and "current" (new content map implementation), though "this" is still supported for legacy templates. See also Template development.

Notes on Tomcat 9

Tomcat 9 creates files with a restricted set of permissions. This is especially relevant for the files in the cache directory. These files should be read by the apache process and thus, should be readable by all users. Otherwise the apache process can’t read the files in the cache directory and all requests are served dynamically by the tomcat.

To fix this problem, the umask for the Tomcat must be changed. This is done by an environment variable:

export UMASK=0002

Apache Webserver Configuration

The webserver is installed in the following directory: install-path/apps/apache2
The httpd.conf file of the webserver contains the hereafter listed Sophora-specific entries:

### sophora configuration
JkWorkersFile "conf/workers.properties"
JkLogFile "logs/mod_jk.log"
JkLogLevel error
JkLogStampFormat "[%a %b %d %H:%M:%S %Y] "
JkOptions +ForwardKeySize +ForwardURICompat +ForwardDirectories
JkRequestLogFormat "%w %V %T"
LoadModule sophora_module modules/mod_sophora.so
# # VirtualHosts
Include /cms/ts/webapps/ts-preprod-live/conf/ts_httpd.conf
Include /cms/ts/webapps/ts-prod-live/conf/ts_httpd.conf

Connection between Apache and Tomcat

To connect the Tomcat with an Apache webserver it is important to set the sophora.delivery.render.isMounted property in the corresponding context to true. Additionally, the DocumentRoot from the Apache's configuration (see below) has to equal the sophora.delivery.cache.directory of the context.

Example

Excerpt from sophora.properties:

sophora.delivery.render.isMounted=true
sophora.delivery.cache.enabled=true
sophora.delivery.cache.directory=/cms/webapps/example-prod-live/cache/htdocs/example

Excerpt from Apache virtual host config:

<VirtualHost www.example.com:80>
    ...
        DocumentRoot /cms/webapps/example-prod-live/cache/htdocs/example
    ...

We recommend using mod_proxy to manage communication between Apache and Tomcat. In comparison to mod_jk and mod_ajp_proxy, mod_proxy has yielded the best results stability and performance.

mod_jk

1. problem: mod_jk is often unavailable for the Apache and need to be translated. Older versions sometimes cause trouble.
2. problem: Apache 1 prevented the execution of the SSI filter within the webserver after the creation of a file in the Tomcat. In Apache 2 this works.
3. problem: If the Tomcat generates a PHP page, the Apache only delivers plain PHP code. The code isn't interpreted until a second call (at that point the file is in the docroot directory and the Tomcat isn't required).

mod_proxy

The mod_proxy configuration is similar to mod_jk solution. However, the mod_proxy is more standard like and easier to use. But the problems remain the same: SSI is only supported by the Apache 2 and PHP isn't interpreted in the first place.

Here is an exemplary Apache configuration with this context: sophora.delivery.cache.directory=/cms/webapps/example-prod-live/cache

<VirtualHost www.example.com:80>
    UseCanonicalName On
        DocumentRoot /cms/webapps/example-prod-live/cache/htdocs/example
        LogLevel warn
 
        ProxyPreserveHost On
 
        AddOutputFilter INCLUDES .html .php .jsp .xml
 
        <Location /example-prod-live>
             SetOutputFilter INCLUDES
        </Location>
 
        AddCharset UTF-8 .html
 
        ProxyRequests Off
        ProxyMaxForwards 50
        ProxyErrorOverride Off
        ProxyPass /example-prod-live/ http://localhost:8080/example-prod-live/
        ProxyPassReverse /example-prod-live/ http://localhost:8080/example-prod-live/
        # Die Verbindung per AJP macht oft Probleme
        # ProxyPass  /example-prod-live/ ajp://localhost:8009/example-prod-live/
        # ProxyPassReverse  /example-prod-live/ ajp://localhost:8009/example-prod-live/
 
        RewriteEngine on
        RewriteLog /cms/webapps/example-prod-live/logs/example_rewrite_log
        RewriteLogLevel 0
 
        <Directory />
                Options Includes ExecCGI FollowSymLinks
        </Directory>
 
        # Add missing trailing slash for directories
        RewriteCond    %{DOCUMENT_ROOT}/%{SCRIPT_FILENAME}  -d
        RewriteRule    ^(.+[Sophora Delivery^/])$ $1/  [R,L]
 
        # Redirect to homepage
        RewriteCond %{SCRIPT_FILENAME} ^/$
        RewriteRule ^/$ /index.html
 
        # Replacement for DirectoryIndex
        RewriteRule ^(.*)/$ $1/index.html
 
        # Use tomcat for dynamic content
        RewriteCond %{SCRIPT_FILENAME} !^/example-prod-live/(.*)$
        RewriteCond %{SCRIPT_FILENAME} ^/.*\.jsp$
        RewriteRule ^/(.*)$ /example-prod-live/example/$1 [PT]
 
        # If we reach this point it must be cacheable content
        RewriteCond %{DOCUMENT_ROOT}%{SCRIPT_FILENAME} !-f
        RewriteRule ^/(.*)$ /example-prod-live/example/$1 [PT]
</VirtualHost>

Tomcat Configuration

The Tomcat is located at install-path/apps/tomcat. It needs to be started by the user "sophora" using the command ./startup.sh in the directory install-path/apps/tomcat/bin. In the same directory you can stop the Tomcat using the command ./shutdown.sh. Within all servers the Tomcat is configured to listen to port 9000. The configuration of the individual context is located in the install-path/apps/tomcat/conf/Catalina/localhost directory.

The context-xml file for each webapp (tomcat/conf/Catalina/localhost/<contextname>.xml) must contain two settings:

• The parameter localConfigDirectory: path of the directory, where the local sophora.properties file of the webapp is located.
• The environment variable logPath: path of the directory where the logs should be written.

Example context-xml:

<?xml version='1.0' encoding='utf-8'?>
<Context docBase="/cms/ndr/webapps/ndr-prod-live/webapp" path="/ndr-prod-live" reloadable="false" override="true">
        <Parameter name="localConfigDirectory" value="/cms/ndr/webapps/ndr-prod-live/conf/"/>
        <Environment name="logPath" value="/cms/ndr/webapps/ndr-prod-live/logs" type="java.lang.String"/>
</Context>

To avoid excessive memory ussage the tag pool size should be set to zero in the tomcat web.xml:

<servlet>
	<servlet-name>jsp</servlet-name>
	<servlet-class>org.apache.jasper.servlet.JspServlet</servlet-class>
	<init-param>
 		<param-name>tagpoolMaxSize</param-name>
 		<param-value>0</param-value>
 	</init-param>
	<load-on-startup>3</load-on-startup>
</servlet>

Configuration of the Sophora Delivery Web Application(s)

Web applications are located in the server's install-path/webapps directory. There you'll find a subdirectory for every context. For example:

install-path/webapps/ts-prod-live

Every context contains the following subdirectories:

• cache
• conf
• logs
• webapp

The webapplication will be deployed in the webapp subfolder. Jenkins is recommended for the deployment process. You can find more information about Jenkins in the section Deployment.

The configuration files are located in the conf directory. There you'll find the central configuration file sophora.properties for the web appliction as well as configuration files for the virtual hosts.

Exemplary sophora.properties file:

sophora.serviceUrl=rmi://www.sophora-cms.com:1199/ContentManager
sophora.delivery.client.username=webadmin
sophora.delivery.client.password=admin
 
sophora.delivery.render.isMounted=false
sophora.delivery.render.isLive=false
 
sophora.delivery.cache.enabled=false
sophora.delivery.cache.directory=C:/repos/sophora_web/cache
 
sophora.delivery.cache.pregeneration.enabled=false
sophora.delivery.cache.pregeneration.maxAccessTimeInterval=180
sophora.delivery.cache.pregeneration.numberOfThreads=1
sophora.delivery.cache.pregeneration.httpTimeout=240
sophora.delivery.url=http://localhost:8080/sophora-ts

sophora.delivery.externalUrl=http://www.sophora-cms.com:8080/sophora-ts
sophora.delivery.cache.groups=group1
 
log4j.logger.com.subshell.sophora.delivery.cache=INFO
log4j.rootLogger=WARN,stdout,logfile

An overview of all configuration parameters can be found in section Configuration Parameters.

Local Configuration Directory

The local configuration directory contains a sophora.properties file that overwrites the settings as defined in the web project's configuration file src/web/WEB_INF/sites/sophora.properties. Thus, for properties that exist in both files, the values from the local one replace those from the global (project wide) configuration file. During development, it might be useful to disable the caching locally or to change the server connection details without changing the entire project configuration.

The delivery requires a sophora.properties file within the local configuration folder. If this file is empty, all properties are retained from the global configuration file. If the local sophora.properties files cannot be detected, the delivery startup fails. In the following example the server connection details are overwritten:

local_sophora.properties

#sophora.serviceUrl=http://cms.server.com:1199
sophora.serviceUrl=localhost:1199
sophora.delivery.client.username=admin
sophora.delivery.client.password=adminPassword

Running the web application from an IDE

When running the webapp from Eclipse (on an embedded Tomcat), The path to the local configuration has to be specified within the src/web/META-INF/context.xml as follows:

context.xml

<?xml version='1.0' encoding='utf-8'?>
<Context>
    <Parameter name="localConfigDirectory" value="c:\sophora\webapp\localConfigurationDir"/>
</Context>

Configuring Websites within the Web Project

• For each website the directory src/web/WEB-INF/sites has to contain a file <sitename>.properties. As with the sophora.properties, the properties given in the <sitename>.properties files can be overwritten in the correspondent files that are located in the local configuration directories. Templates then apply the properties dependent on the website the user is currently viewing.
• Also, the directory src/web/WEB-INF/templates/<sitename> has to contain a file templates.xml. Within this file, it is determined which JSP templates should be used when a certain document type is requested. For more information see the page templates.xml.

Configuration Parameters

The following table contains all possible configuration parameters, a brief description and, if non-trivial, an exemplary value.

Caching

Filesystem Cache Folders

The subdirectory install-path/webapps/context/cache contains

• a directory db and
• a directory removal and
• a link htdocs -> ../../../htdocs/ts-prod-live.

The directory db is the location of the registry of the cache manager. The directory removal contains the persistent data of the removal- as well as the preGenerating queue. The link htdocs ensures that the HTML cache is located at a defined position within the directory structure but may be spotted elsewhere if necessary.

Configuring the Derby Cache DB

To deactivate the optimization of storage space within the Derby DB, you have to set the property sophora.delivery.cache.derby.optimizing.enabled to false. The database optimization is executed once a day at 3am by default, but can be changed via the property sophora.delivery.cache.derby.optimizing.cron.

Logging

Log4J has been removed as the logging framework for the delivery, in favour of SLF4J. SLF4J is a logging facade, a backend has to be provided by the web-application. This allows any SLF4J-compliant logging framework to be used in the web-application, such as log4j or logback. We recommend using logback, because it supports automatic reloading of the configuration file and configuration via JMX.

A logging configuration and the .jars of the logging backend must be provided by the web-application.

To configure logging using logback, a logback.xml file has to be added to the web-application's classpath (e.g. under WEB_INF/classes). The following example shows a configuration that behaves similar to the log4j-configuration used in previous sophora releases:

<?xml version="1.0" encoding="UTF-8"?>
 
<configuration scan="true">
    <jmxConfigurator />
    <insertFromJNDI env-entry-name="java:comp/env/logPath" as="LOGPATH" />
 
    <appender name="STDOUT" class="ch.qos.logback.core.ConsoleAppender">
        <encoder>
            <pattern>[%thread|%thread] %-5level %.40c:%L - %msg %n</pattern>
        </encoder>
    </appender>
 
    <appender name="logfile" class="ch.qos.logback.core.rolling.RollingFileAppender">
        <File>${LOGPATH}/delivery.log</File>
 
        <rollingPolicy class="ch.qos.logback.core.rolling.TimeBasedRollingPolicy">
            <fileNamePattern>${LOGPATH}/delivery.%d{yyyy-MM-dd}.log
            </fileNamePattern>
            <maxHistory>7</maxHistory>
        </rollingPolicy>
        <encoder>
            <pattern>[%d{ISO8601}, %-5p] [%t|%t] %m%n</pattern>
        </encoder>
    </appender>
 
    <appender name="cachefile" class="ch.qos.logback.core.rolling.RollingFileAppender">
        <File>${LOGPATH}/cache.log</File>
 
        <rollingPolicy class="ch.qos.logback.core.rolling.TimeBasedRollingPolicy">
            <fileNamePattern>${LOGPATH}/cache.%d{yyyy-MM-dd}.log
            </fileNamePattern>
            <maxHistory>7</maxHistory>
        </rollingPolicy>
        <encoder>
            <pattern>[%d{ISO8601}] [%t|%t] %m%n</pattern>
        </encoder>
    </appender>
 
    <appender name="errorLog" class="ch.qos.logback.core.rolling.RollingFileAppender">
        <filter class="ch.qos.logback.classic.filter.ThresholdFilter">
            <level>ERROR</level>
        </filter>
 
        <File>${LOGPATH}/error.log</File>
 
        <rollingPolicy class="ch.qos.logback.core.rolling.TimeBasedRollingPolicy">
            <fileNamePattern>${LOGPATH}/error.%d{yyyy-MM-dd}.log
            </fileNamePattern>
            <maxHistory>7</maxHistory>
        </rollingPolicy>
        <encoder>
            <pattern>[%d{ISO8601}, %-5p] [%t|%t] %.40c:%L: %m%n</pattern>
        </encoder>
    </appender>
 
    <logger name="org.apache.commons.httpclient" level="ERROR" />
    <logger name="com.subshell.sophora" level="WARN" />
    <logger name="com.subshell.sophora.delivery.filter.BenchmarkFilter" level="INFO" />
    <logger name="com.subshell.sophora.delivery.cache" level="INFO" additivity="false">
        <appender-ref ref="cachefile" />
    </logger>
 
    <root level="WARN">
        <appender-ref ref="logfile" />
        <appender-ref ref="errorLog" />
    </root>
</configuration>

Using this configuration, logback will write the logfiles:

• delivery.log
• cache.log
• error.log

in the [LOGPATH] directory. This should be the same place where the former log4j default-configuration placed the logfiles. This configuration uses LOGPATH as a placeholder for the logs directory. So this configuration can be used for multiple installations.

To define the LOGPATH variable, a java.lang.String-resource has to be provided by the container. This resource can be added to the context in the container's context-configuration (e.g. context.xml):

<?xml version='1.0' encoding='utf-8'?>
<Context>
...
    <Environment name="logPath" value="/cms/portal/webapps/myportal/logs" type="java.lang.String"/>
...
</Context>

The LOGPATH variable can also be set in the application's web.xml using the following definition. This is only recommended if the configuration via the context is insufficient or not possible for any reason.

web.xml

<env-entry>
  <env-entry-name>logPath</env-entry-name>
  <env-entry-type>java.lang.String</env-entry-type>
  <env-entry-value>/cms/portal/webapps/myportal/logs</env-entry-value>
</env-entry>

In addition, this directory contains - depending on the webserver's configuration - log files for each website:

• <site>_access_log (e.g. ts_access_log)
• <site>_error_log
• <site>_rewrite_log

Finally the following .jars have to be present in the web-application's classpath (WEB-INF/lib):

• logback-classic-0.9.27.jar
• logback-core-0.9.27.jar
• slf4j-api-1.6.1.jar

If maven is used in the web-project the following dependency can be added to the pom:

<dependency>
 <groupId>ch.qos.logback</groupId>
 <artifactId>logback-classic</artifactId>
 <version>0.9.27</version>
 <type>jar</type>
</dependency>

Recommended Configuration for productive environments

When setting up Sophora deliveries in production mode, you should have a look at our recommended settings for productive environments which contains a section on deliveries.

web.xml

Filters

Each request is filtered by several servlet filters within the web application. Depending on the configuration filters may be omitted or disabled. The following sections describe how the filters can be defined in the web.xml and by which parameters they can be configured. For more information about filters read the section The Sophora Filter Chain.

Standard Filters

SiteEnvironmentSetupFilter

<filter>
    <filter-name>SiteEnvironmentSetupFilter</filter-name>
    <filter-class>
        com.subshell.sophora.delivery.filter.SiteEnvironmentSetupFilter
    </filter-class>
    <init-param>
        <param-name>resourcePathRegex</param-name>
        <param-value>\.servlet</param-value>
    </init-param>
</filter>

SSIFilter

<filter>
    <filter-name>SSIFilter</filter-name>
    <filter-class>com.subshell.sophora.delivery.filter.SSIFilter</filter-class>
    <init-param>
        <param-name>contentTypePrefixes</param-name>
        <param-value>text,application/xml,application/json</param-value>
    </init-param>
</filter>

CacheFilter

<filter>
    <filter-name>CacheFilter</filter-name>
    <filter-class>
        com.subshell.sophora.delivery.cache.filter.CacheFilter
    </filter-class>
    <init-param>
        <param-name>encoding</param-name>
        <param-value>UTF-8</param-value>
    </init-param>
    <init-param>
        <param-name>noCachingSuffixes</param-name>
        <param-value>.servlet</param-value>
    </init-param>
</filter>

SophoraSessionFilter

<filter>
    <filter-name>sophoraSessionFilter</filter-name>
    <filter-class>
        com.subshell.sophora.delivery.filter.SophoraSessionFilter
    </filter-class>
</filter>

UrlDecoderFilter

<filter>
    <filter-name>URLDecoderFilter</filter-name>
    <filter-class>com.subshell.sophora.delivery.filter.URLDecoderFilter</filter-class>
    <init-param>
        <param-name>ignoreSuffixes</param-name>
        <param-value>.servlet</param-value>
    </init-param>
</filter>

Additional (optional) Filters

SetUtf8EncodingFilter

<filter>
    <filter-name>sophoraUtf8EncodingFilter</filter-name>
    <filter-class>
        com.subshell.sophora.delivery.filter.SetUtf8EncodingFilter
    </filter-class>
</filter>

BenchmarkFilter

<filter>
    <filter-name>benchmarkFilter</filter-name>
    <filter-class>
        com.subshell.sophora.delivery.filter.BenchmarkFilter
    </filter-class>
</filter>

MultipartFilter

<filter>
    <filter-name>multipartFilter</filter-name>
    <filter-class>com.subshell.sophora.delivery.filter.MultipartFilter</filter-class>
</filter>

ExceptionLoggingFilter

<filter>
    <filter-name>exceptionFilter</filter-name>
    <filter-class>
        com.subshell.sophora.commons.filter.ExceptionLoggingFilter
    </filter-class>
</filter>

TrimFilter

<filter>
    <filter-name>trimFilter</filter-name>
    <filter-class>
        com.subshell.sophora.commons.filter.TrimFilter
    </filter-class>
</filter>

Sophora Initializer

The SophoraInitializer needs to be defined as a listener. It takes care of initializing the properties, templates and spring configurations.

<listener>
    <listener-class>
        com.subshell.sophora.delivery.configuration.SophoraInitializer
    </listener-class>
</listener>

Servlets

To enable servlets, the suffix of the servlets must be excluded from certain Sophora filters.
To exclude certain suffixes from caching the cache filter needs to be configured by setting the parameter noCachingSuffixes in the web.xml like in the following example (the excluded suffix is ".servlet"):

<filter>
    <filter-name>CacheFilter</filter-name>
    <filter-class>
        com.subshell.sophora.delivery.cache.filter.CacheFilter
    </filter-class>
    <init-param>
        <param-name>encoding</param-name>
        <param-value>UTF-8</param-value>
    </init-param>
    <init-param>
        <param-name>noCachingSuffixes</param-name>
        <param-value>.servlet</param-value>
    </init-param>
</filter>

To ignore suffixes in the URLDecoderFilter the ignoreSuffixes parameter has to be used:

<filter>
    <filter-name>URLDecoderFilter</filter-name>
    <filter-class>
        com.subshell.sophora.delivery.filter.URLDecoderFilter
    </filter-class>
    <init-param>
        <param-name>ignoreSuffixes</param-name>
        <param-value>.servlet</param-value>
    </init-param>
</filter>

Get the document uuid for a URL (idForUrl.servlet)

There are some configurations to do in delivery in order to provide the "Open document by URL from clipboard" action within the main menu of the Deskclient. To configure the new idForUrl.servlet execute the steps below:

1. Add to the web.xml file:

<servlet>
<servlet-name>idForUrlServlet</servlet-name>
<servlet-class>com.subshell.sophora.delivery.servlet.IdForUrlServlet</servlet-class>
</servlet>
 
<servlet-mapping>
<servlet-name>idForUrlServlet</servlet-name>
<url-pattern>/system/servlet/idForUrl.servlet</url-pattern>
</servlet-mapping>

1. Finally, the template for the preview (preview.jsp) needs to evaluate the new parameter idForUrl, and possibly forward to the servlet:

<%@ page session="false" pageEncoding="utf-8" contentType="text/html; charset=UTF-8"%>
<%@ taglib uri="http://java.sun.com/jsp/jstl/core" prefix="c" %>
<%@ taglib tagdir="/WEB-INF/tags/sophora-commons" prefix="sc"%>
<%@ taglib uri="http://www.subshell.com/sophora/jsp" prefix="sophora" %>
 
<c:choose>
    <c:when test="${param.idForUrl eq 1}">
        <c:set var="redirectUrl" >/system/servlet/idForUrl.servlet?url=${param.url}</c:set>
        <c:import url="${redirectUrl}" />
    </c:when>
    <c:otherwise>
        <c:choose>
            <c:when test="${param.print eq 1}">
                <sophora:map sophoraid="${param.sophoraid}" doprint="${param.doprint}" admin="${param.admin}" var="params" />
                <sophora:staticUrl path="/system/print.jsp" params="${params}" var="redirectUrl"/>
            </c:when>
            <c:when test="${!empty param.path}">
                <sophora:url structureNodeUuid="${param.path}" var="redirectUrl" />
            </c:when>
            <c:otherwise>
                <sc:createLink sophoraId="${param.sophoraid}" urlOnly="true" var="redirectUrl" />
            </c:otherwise>
        </c:choose>
    <?xml version="1.0" encoding="UTF-8" ?>
    <html>
        <head>
            <c:if test="${!empty redirectUrl}">
                <meta http-equiv="refresh" content="0; URL=${redirectUrl}">
            </c:if>
        </head>
        <body>
            <c:if test="${empty redirectUrl}">
                <b>Es wird kein Inhalt für dieses Dokument ausgespielt!</b>
            </c:if>
        </body>
    </html>
    </c:otherwise>
</c:choose>

To test whether the configuration is successful, you can call the preview.jsp with a queryString ?idForUrl=1&url='AnyPreviewUrl'. The result of that request should be the UUID of the document shown in 'AnyPreviewUrl'.

Cache Servlet

Error-Sites

To configure error sites which will be rendered by the tomcat, they have to be configured in the DeskClient first. Within the property labeled 404-Error-Documents (sophora:notFoundErrorDocument) on the configuration tab of a structure node, you can define error documents which will be delivered when a document is not found under the configured structure node. By default, this property inherits its value from parent structure nodes. The resulting site will have the status code 404 (Not Found).

Then, some additional configuration is needed:

• ProxyErrorOverride in the apache configuration has to be set to off, so the tomcat can deliver its own error sites.
• In the web.xml you have to define jsp files which will be delivered as the default error page if there is no error document configured for an 404 request.

<error-page>
	<error-code>404</error-code>
	<location>/404.jsp</location>
</error-page>
<error-page>
	<error-code>403</error-code>
	<location>/403.jsp</location>
</error-page>
<error-page>
	<error-code>500</error-code>
	 <location>/500.jsp</location>
</error-page>

• The jsp files have to be placed directly under the webapp directory and have the following content:

<%@ page contentType="text/html; charset=UTF-8"%>
<%@ taglib prefix="c" uri="http://java.sun.com/jsp/jstl/core"%>
 
<c:set var="contextPath" value="${pageContext.request.scheme}://${pageContext.request.serverName}:${pageContext.request.serverPort}${pageContext.request.contextPath}" />
 
<c:import url="${contextPath}/site/404-error100.html"/>

• The hostname, port and context path are set automatically. In this example a request resulting in a 404 error will show the sophora document 404-error100. The same has to be done for 403 and 500 error documents.

Deployment

The delivery webapplication is usually built and assembled by maven and managed over SVN or any other source code management system. The following section describes how Jenkins can be used to automatically checkout, build and deploy webapplications based on the sophora delivery infrastructure.

Jenkins

Jenkins is a java webapplication that monitors executions of jobs, such as building or deployning a software project. Jenkins integrates easily with SVN and Maven so that both technologies can be embedded in the deployment process. While using Jenkins it's possible to trigger deployment jobs either manually or based on events like a commit into the SVN. Each job can be configured and monitored by the Jenkins UI. For more information visit the Jenkis homepage.

The following section describes how to setup a simple deploy job for a delivery webapplication.

Deploy Job

• To setup a Job just open the Jenkins UI in a browser and click on new Job in the menu on the left.
• Enter a descriptive name for the job and choose Build a free-style software project from the selection under the Job name textfield.
• Click ok to save your selection an go on with the configuration.
• choose Subversion in the section Source Code Management and enter the Repository URL to the module you want to build and deploy
• choose the event that starts the Job in the Build Triggerssection
• choose Build after other projects are built to make the Job dependent from other jobs e.g. test runs
• choose Poll SCM if you want to start the job after a SVN commit (This might be useful for development and test environments)
• leave the selection blank if you want to start the job manually
• add a build step Invoke top-level Maven targets in the Build section
• after jenkins checked out or updated the project we want to build a war file that will be deployed on a servlet engine. So enter clean package as Goals
• add another build step Execute shell
• finally we have setup the deployment of the war file that has been build in the previous step. The following script copies the packaged war file to the delivery servers via rsync over ssh.

cd "${WORKSPACE}/target"
# Change into the directory of the assembled webapp.
WEBAPP_DIR="$(ls -1 *.war | sed -r -e 's|\.war$||')"
cd "${WEBAPP_DIR}"
 
# Copy webapp.
rsync --rsh "ssh -C" --delete -avz -c "." "sophora@${TARGET_HOST}:${TARGET_WEBAPP_DIR}"

where

• TARGET_HOST is the host where the application will be deployed and
• TARGET_WEBAPP_DIR is the full qualified path to the context root of the webapplication

Mirroring

Static content is mirrored to several delivery machines by the mirror.sh script. This script mirrors a directory from the machine on which it is run to all Staging Servers that are connected to a Sophora Primary Server. The transfer is done via rsync on SSH.

The following settings can be configured in the script's head:

To start the script prompt ./mirror.sh. If want to stop it, you can press CTRL+C or enter kill at the process ID anytime. Before stopping the script completes the current mirroring job.