This topic describes how to set up an XperienCentral installation in a Linux production environment. The result is that all requests for static content (images, style sheets, etc.) are handled through the web server and requests for dynamic content (XperienCentral’s HTML) are forwarded by the web server to XperienCentral which processes the requests. In this topic, an environment will be created with two host names:
External host name: www.mywebsite.com
Internal host name: edit.mywebsite.com
In This Topic
The Directory Structure
After installing XperienCentral, a directory structure is created. You are free to choose your own structure, but GX recommends the following:
/vol/www/server/ | Apache Tomcat web server location |
/vol/www/tomcat-mywebsite/deploy | Tomcat directory |
/vol/www/mywebsite/configuration/ | Contains the configuration.xml file |
/streaming/ | ♦ Website downloads |
/system/ | ♦ System files |
/web-docs/cfg/ | ♦ Flash element configuration |
/toolbar/ | Poll element files |
/upload/ | Page images |
/upload_mm/ | Content Repository images |
/wm/ | Standard XperienCentral files |
/work/cache/ | Cache for plugins and pages |
/deploy/ | Plugins |
/edition-bundles/ | ♦ Source files for XperienCentral plugins |
/formupload/ | Binaries of sent forms |
/jcr/ | JCR-related files |
/osgi/ | Cache for OSGi framework files |
/undo/ | Cache for the undo/redo functionality |
You can create all or part of this directory structure before starting the entire installation process. Create the directories marked with ♦ before starting the installation. The others will be created later in this topic.
Java Development Kit
XperienCentral uses the Java SE Development Kit (JDK) which can be downloaded from: http://www.oracle.com/technetwork/java/javase/downloads.
- Use Java version 8.
- Use the 64-bit version of Java if possible.
- Official support for Java 7 ended in April 2015.
Download and install the JDK 8.0 for your platform Example UNIX commands for the JDK 8.0 installation:
cd /usr mkdir java cd java chmod 700 /tmp/jdk-8-linux-i586-rpm /tmp/jdk-8-linux-i586-rpm rm -f /tmp/jdk-8-linux-i586-rpm ln -sf /usr/java/jdk8 /usr/java/jdk1.8
Verify that the new JDK is being used: After entering java –version
, the Java version number is displayed. If it is not the correct version, modify the PATH
variable and point it to the correct version.
Setting environment variables is best done in the startup script of the shell being used (~/.profile
or ~/.cshrc
for example). This adds the variable permanently so you do not have to enter the export command multiple times.
Apache Maven
To install XperienCentral, use the Maven build tool. This tool can be downloaded from: http://maven.apache.org/. Download and install version 3.3.xx. For example:
cd /usr/local/ tar zxf /tmp/apache-maven-3.3.xx-bin.tar.gz rm -rf /tmp/apache-maven-3.3.xx* ln -sf apache-maven-3.3.xx
After the installation, Maven will still have to be recorded in the PATH
variable and the M2_HOME
variable will need to be set. For example:
export PATH=/usr/java/jdk1.8/bin:$PATH export PATH=/usr/local/maven/bin:$PATH export M2_HOME=/usr/local/maven/ export JAVA_HOME=/usr/java/jdk1.8/
Verify that the new version of Maven is being used. After entering mvn –version
, the Maven version number is displayed. If an older version is indicated, remove the Maven version already on the system.
The Database
XperienCentral works with the following databases:
- Oracle
- MSSQL
- MySQL
For the exact versions of the above listed databases, see the XperienCentral hardware and software requirements. Install one of the databases and create a username and password for someone with permission to create and fill a table. The following are example UNIX commands for MySQL in a Red Hat Enterprise Linux environment:
cd /tmp rpm -i MySQL-server-community-5.0.45-0.rhel4.i386.rpm rpm -i MySQL-client-community-5.0.45-0.rhel4.i386.rpm rpm -i MySQL-shared-community-5.0.45-0.rhel4.i386.rpm /usr/bin/mysqladmin -u root password '<myDBpassword>'
The default MySQL settings need to be adjusted to make it work smoothly with XperienCentral. Create the file my.cnf
and place it in the directory /etc
. The initial contents of this file should be:
[mysqld] max_allowed_packet=512M innodb_buffer_pool_size=256M [mysqldump] max_allowed_packet=512M
For MySQL versions 5.7 and higher, add the following to the [mysqld]
section:
optimizer_switch = derived_merge=off
Restart MySQL after you have changed the /etc/my.cnf
file.
The Application Server (Tomcat or JBoss)
XperienCentral runs within an application server. Install either Tomcat or Jboss (not both).
Tomcat
Download the latest version of Apache Tomcat 7.0 (http://tomcat.apache.org/download-70.cgi) and unpack it in the /vol/www/
directory. Rename the created directory tomcat-
mywebsite
. For example:
cd /vol/www/ tar zxf /tmp/apache-tomcat-7.0.39.tar.gz mv apache-tomcat-7.0.39 tomcat-mywebsite rm -f /tmp/apache-tomcat-7.0.39.tar.gz # Also add the directories for the expanded XperienCentral files cd tomcat-mywebsite mkdir deploy mkdir deploy/appBase
Add the following lines to /vol/www/tomcat-mywebsite/bin/catalina.sh
, directly under the first block of comment lines:
CATALINA_HOME=/vol/www/tomcat-mywebsite JAVA_HOME=/usr/java/jdk1.8 JAVA_OPTS="${JAVA_OPTS} -Dsun.rmi.dgc.server.gcInterval=600000" JAVA_OPTS="${JAVA_OPTS} -Dsun.rmi.dgc.client.gcInterval=600000" JAVA_OPTS="${JAVA_OPTS} -Duser.language=en -Duser.country=US" JAVA_OPTS="${JAVA_OPTS} -XX:+UseConcMarkSweepGC" JAVA_OPTS="${JAVA_OPTS} -Djava.awt.headless=true" JAVA_OPTS="${JAVA_OPTS} -Dwebmanager.clustering.readonly=false" JAVA_OPTS="${JAVA_OPTS} -Dsun.net.inetaddr.ttl=300" JAVA_OPTS="${JAVA_OPTS} -Djavax.xml.transform.TransformerFactory=com.sun.org.apache.xalan.internal.xsltc.trax.TransformerFactoryImpl" JAVA_OPTS="${JAVA_OPTS} -Xmx1024M -Xms512M" JAVA_OPTS="${JAVA_OPTS} -XX:-ReduceInitialCardMarks" JAVA_OPTS="${JAVA_OPTS} -Dorg.apache.jasper.runtime.JspFactoryImpl.USE_POOL=false" JAVA_OPTS="${JAVA_OPTS} –Dwebmanager.clustering.id=x" JAVA_OPTS="${JAVA_OPTS} -Djava.net.preferIPv4Stack=true"
The settings used in the above example are good defaults and need no adjusting. The only parameter that might need adjusting is the Xmx
parameter. The number in the Xmx
parameter determines the maximum RAM allowed for the Java process in which XperienCentral runs. In this example, the RAM is set at 1024 MB (1 GB). The higher this number is set, the smoother XperienCentral will run.
In a clustered environment, substitute the x
in JAVA_OPTS="${JAVA_OPTS} –Dwebmanager.clustering.id=x
with a unique name for each node in the cluster (GX recommends using the name of the server for the clustering ID). For a slave node one setting has to be adjusted: set the property webmanager.clustering.readonly
to true
. See Distributed XperienCentral (Linux) for complete information about setting up a clustered environment.
See JAVA_OPTS Parameters for more details and explanations on the JAVA_OPTS
settings.
Avoiding Clogged Logfiles
With the default settings, the log file will be quickly filled with messages, (information, warning, and error). GX Software recommends adjusting the logging.properties file in Tomcat in order to reduce the number of messages that are logged. Proceed as follows:
- Open the
/vol/www/tomcat-mywebsite/conf/logging.properties
file. - At the end of the file, add the following lines:
nl.gx.level = WARNING org.apache.felix.level = WARNING org.apache.jackrabbit.level = WARNING org.apache.solr.level = WARNING org.quartz.level = WARNING org.springframework.level = WARNING nl.gx.webmanager.startup.level = INFO # Upgrade bundle logging nl.gx.webmanager.services.upgrade.impl.level = INFO #OpenID org.verisign.joid.level = WARNING
JBoss
Download JBoss EAP 6.3.3 (http://jbossas.jboss.org/downloads/) and unpack it in the /vol/www/
directory. Rename the created directory jboss-
mywebsite
. Add the following lines to /vol/www/jboss-mywebsite/bin/standalone.conf
, directly under the first block of commented lines:
JAVA_OPTS="${JAVA_OPTS} -Dsun.rmi.dgc.server.gcInterval=600000" JAVA_OPTS="${JAVA_OPTS} -Dsun.rmi.dgc.client.gcInterval=600000" JAVA_OPTS="${JAVA_OPTS} -Duser.language=en -Duser.country=US" JAVA_OPTS="${JAVA_OPTS} -XX:+UseConcMarkSweepGC" JAVA_OPTS="${JAVA_OPTS} -Djava.awt.headless=true" JAVA_OPTS="${JAVA_OPTS} -Dwebmanager.clustering.readonly=false" JAVA_OPTS="${JAVA_OPTS} -Dsun.net.inetaddr.ttl=300" JAVA_OPTS="${JAVA_OPTS} -Djavax.xml.transform.TransformerFactory=com.sun.org.apache.xalan.internal.xsltc.trax.TransformerFactoryImpl" JAVA_OPTS="${JAVA_OPTS} -Xmx1024M -Xms512M" JAVA_OPTS="${JAVA_OPTS} -XX:-ReduceInitialCardMarks" JAVA_OPTS="${JAVA_OPTS} -Dorg.apache.jasper.runtime.JspFactoryImpl.USE_POOL=false" JAVA_OPTS="${JAVA_OPTS} –Dwebmanager.clustering.id=x"
By default, the settings in the above example need no further adjusting. The only parameter that you might have to change is the Xmx
parameter. The value of the Xmx
parameter determines the maximum amount of RAM allowed for the Java process in which XperienCentral runs. In the above example, the maximum amount of RAM is set to 1024 MB (1 GB). The higher this number is set, the better the performance you will have.
See JAVA_OPTS Parameters for more details and explanations on the JAVA_OPTS
settings.
The above settings are OK for a standalone setup of XperienCentral and the setup of a master node in a clustered environment. For a slave node one setting has to be adjusted: set the property webmanager.clustering.readonly
to true
.
Avoiding Clogged Logfiles
With the default settings, the log file will be quickly filled with messages, (INFO, WARN, and ERROR). To reduce the number of messages that are logged, adjust the (JBoss)/JBoss-My Website/standalone/configuration/standalone.xml
file and add the following loggers where the other logger tags are located in the jboss.domain.logging
subsystem:
<logger category="org.apache.felix"> <level name="WARN"/> </logger> <logger category="org.apache.jackrabbit"> <level name="WARN"/> </logger> <logger category="org.apache.solr"> <level name="WARN"/> </logger> <logger category="org.quartz"> <level name="WARN"/> </logger> <logger category="org.springframework"> <level name="WARN"/> </logger> <logger category="nl.gx.webmanager.startup"> <level name="INFO"/> </logger> <logger category="nl.gx.webmanager.services.upgrade.impl"> <level name="INFO"/> </logger>
Apache Web Server
Download the latest version of the Apache web server (http://httpd.apache.org/download.cgi) and install it. How to compile Apache is explained in the examples below. It is also possible to use the Apache included in the package. Because of the Apache package updates, it is recommended that you configure Apache as far as possible according to the package standards, for example, by including configuration files instead of modifying the httpd.conf
itself.
Configuration of httpd.conf
For the httpd.conf
file, XperienCentral requires at a minimum the following extra modules:
mod_proxy.so
mod_proxy_http.so
mod_proxy_ajp.so
mod_headers.so
mod_expires.so
The httpd-vhosts.conf
file also needs to be read. Locate vhosts
in the httpd.conf
and delete the #
at the beginning of the line:
Include conf/extra/httpd-vhosts.conf
Configuration of httpd-vhosts.conf
The httpd-vhosts.conf
file is located in the /vol/www/server/conf/extra
directory of Apache. The configurations for VirtualHosts
of the front end and back-end are located here.
<VirtualHost *:80> ServerName www.mywebsite.com DocumentRoot "/vol/www/mywebsite/web-docs/" ErrorLog logs/www.mywebsite.com_error.log CustomLog logs/www.mywebsite.com_custom.log common <Directory "/vol/www/mywebsite/web-docs/"> Options +FollowSymLinks +includes AllowOverride All Require all granted </Directory> ProxyPass /web/ ajp://localhost:8009/web/ ttl=600 <IfModule mod_rewrite.c> RewriteEngine On RewriteCond %{REQUEST_URI} !^/web/ RewriteRule ^/(.*)\.htm$ /web/$1.htm [PT,L] </IfModule> </VirtualHost>
The following is the minimal setup of the virtual host for the internal environment of XperienCentral (HTTP):
<VirtualHost *:80> ServerName edit.mywebsite.com DocumentRoot "/vol/www/mywebsite/web-docs/" ErrorLog logs/edit.mywebsite.com_error.log CustomLog logs/edit.mywebsite.com_custom.log common <Directory "/vol/www/mywebsite/web-docs/"> Options +FollowSymLinks +includes AllowOverride All Require all granted </Directory> <Directory "/vol/www/mywebsite/web-docs/wm/b/"> ExpiresActive ON ExpiresDefault "now plus 10 minutes" Header set Cache-Control "max-age=600" </Directory> ProxyPass /web/ ajp://localhost:8009/web/ ttl=600 <IfModule mod_rewrite.c> RewriteEngine On RewriteCond %{REQUEST_URI} !^/web/ RewriteRule ^/(.*)\.htm$ /web/$1.htm [P,L] </IfModule> </VirtualHost>
Backend Configuration of httpd-vhosts.conf for a Redirect to HTTPS
The following is the minimal setup of the virtual host for the internal environment of XperienCentral (HTTPS):
<VirtualHost *:80> ServerName www.mywebsite.com DocumentRoot "/vol/www/mywebsite/web-docs/" ErrorLog logs/www.mywebsite.com_error.log CustomLog logs/www.mywebsite.com_custom.log common <Directory "/vol/www/mywebsite/web-docs/"> Options +FollowSymLinks +includes AllowOverride All Require all granted </Directory> ProxyPass /web/ ajp://localhost:8009/web/ ttl=600 <IfModule mod_rewrite.c> RewriteEngine On RewriteCond %{REQUEST_URI} !^/web/ RewriteRule ^/(.*)\.htm$ /web/$1.htm [PT,L] </IfModule> # Rewrite external requests to https <IfModule mod_rewrite.c> RewriteEngine On LogLevel emerg RewriteCond %{HTTPS} off RewriteCond %{REMOTE_HOST} !###\###\###\###$ (substitute the #s with the IP address of the backend server) RewriteCond %{REMOTE_HOST} !127\.0\.0\.1$ RewriteCond %{REMOTE_HOST} !localhost$ RewriteRule (.*) https://%{HTTP_HOST}%{REQUEST_URI} [L] RewriteRule ^/wm.* - [L] RewriteCond %{REQUEST_URI} !^/web/ RewriteRule ^/(.*)\.htm$ /web/$1.htm [PT,L] </IfModule> </VirtualHost>
Frontend Configuration of httpd-vhosts.conf for an HTTPS Redirect
The following is the minimal setup of the virtual host for an external frontend environment of XperienCentral that redirects to HTTPS:
<VirtualHost *:80> ServerName www.mywebsite.com DocumentRoot "/vol/www/mywebsite/web-docs/" ErrorLog logs/www.mywebsite.com_error.log CustomLog logs/www.mywebsite.com_custom.log common <Directory "/vol/www/mywebsite/web-docs/"> Options +FollowSymLinks +includes AllowOverride All Require all granted </Directory> ProxyPass /web/ ajp://localhost:8009/web/ ttl=600 <IfModule mod_rewrite.c> RewriteEngine On RewriteCond %{REQUEST_URI} !^/web/ RewriteRule ^/(.*)\.htm$ /web/$1.htm [PT,L] </IfModule> # Rewrite external requests to https <IfModule mod_rewrite.c> RewriteEngine On LogLevel emerg RewriteCond %{HTTPS} off RewriteCond %{REMOTE_HOST} !###\###\###\###$ (substitute the #s with the IP address of the frontend server) RewriteCond %{REMOTE_HOST} !127\.0\.0\.1$ RewriteCond %{REMOTE_HOST} !localhost$ RewriteRule (.*) https://%{HTTP_HOST}%{REQUEST_URI} [L] RewriteCond %{REQUEST_URI} !^/web/ RewriteRule ^/(.*)\.htm$ /web/$1.htm [PT,L] </IfModule> </VirtualHost>
Backend Configuration of httpd-vhosts.conf for HTTPS
The following is the minimal setup of the virtual host for an external backend HTTPS environment of XperienCentral:
<VirtualHost *:443> ServerName <server name> ServerAdmin <admin e-mail address> DocumentRoot /vol/webmanager/webmanager-webapps/webmanager-static-webapp/target/webmanager-static-webapp-10.9.0 ErrorLog /vol/httpd/logs/errors-edit-ssl CustomLog /vol//httpd/logs/access-edit-ssl combined ############# # SSL SSLEngine On SSLProxyEngine On SSLProtocol +TLSv1 ## See https://mozilla.github.io/server-side-tls/ssl-config-generator ## for information on other rules you should add here for the version ## of Apache you are using. SSLCertificateFile /vol/httpd/ssl/nolaa.crt SSLCertificateKeyFile /vol/httpd/ssl/nolaa.key SetEnvIf User-Agent ".*MSIE.*" nokeepalive ssl-unclean-shutdown downgrade-1.0 force-response-1.0 # CustomLog /vol/www/server/logs/ssl/ssl_request_log "%t %h %{SSL_PROTOCOL}x %{SSL_CIPHER}x \"%r\" %b" <Directory /vol/webmanager/webmanager-webapps/webmanager-static-webapp/target/webmanager-static-webapp-10.10.0> Options +FollowSymLinks +includes AllowOverride All Require all granted </Directory> <Directory /vol/webmanager/webmanager-webapps/webmanager-static-webapp/target/webmanager-static-webapp-10.9.0/wm/b/toolbar/> ExpiresActive ON ExpiresDefault "now plus 10 minutes" Header set Cache-Control "max-age=600" </Directory> <Directory /vol/webmanager/webmanager-webapps/webmanager-static-webapp/target/webmanager-static-webapp-10.9.0/wm/b/domapi/> ExpiresActive ON ExpiresDefault "now plus 10 minutes" Header set Cache-Control "max-age=600" </Directory> ProxyPass /web/ ajp://localhost:19200/web/ttl=600 ProxyPassReverse /web/ ajp://localhost:19200/web/ <IfModule mod_rewrite.c> RewriteEngine On RewriteLogLevel 0 RewriteCond %{REQUEST_URI} !^/web/ RewriteRule ^/(.*)\.htm$ /web/$1.htm [P,L] </IfModule> Alias /systemlogs /vol/webmanager/apache-tomcat-7.0.39/logs <Location /systemlogs> <IfModule mod_deflate.c> SetOutputFilter DEFLATE </IfModule> AuthUserFile /vol/httpd/htpasswd AuthName "" AuthType Basic Options +Indexes IndexOptions FancyIndexing Order Deny,Allow Allow from all Allow from localhost Allow from <IP address> </Location> ScriptAlias /cgi-bin "/vol/www/server/cgi-bin" </VirtualHost> </IfDefine>
For HTTPS support, you also need to add the –D SSL
flag to the Options=""
line of the /etc/sysconfig/httpd
to enable SSL for the Apache web server.
Frontend Configuration of httpd-vhosts.conf for HTTPS
The following is the minimal setup of the virtual host for an external frontend HTTPS environment of XperienCentral:
<VirtualHost *:443> ServerName <server name> ServerAdmin <admin e-mail address> DocumentRoot /vol/webmanager/webmanager-webapps/webmanager-static-webapp/target/webmanager-static-webapp-10.9.0 ErrorLog /vol/httpd/logs/errors-frontend-ssl CustomLog /vol/httpd/logs/access-frontend-ssl combined ################# # SSL SSLEngine On SSLProxyEngine On SSLProtocol +TLSv1 ## See https://mozilla.github.io/server-side-tls/ssl-config-generator ## for information on other rules you should add here for the version ## of Apache you are using. SSLCipherSuite HIGH:MEDIUM SSLCertificateFile /vol/httpd/ssl/<certificate>.crt SSLCertificateKeyFile /vol/httpd/ssl/<certificate>.key SetEnvIf User-Agent ".*MSIE.*" nokeepalive ssl-unclean-shutdown downgrade-1.0 force-response-1.0 ### CustomLog /vol/www/server/logs/ssl/ssl_request_log "%t %h %{SSL_PROTOCOL}x %{SSL_CIPHER}x \"%r\" %b" # Test: Recognize this VirtualHost Alias /systemlogs2 /vol/webmanager/apache-tomcat-7.0.39/logs <Location /systemlogs2> <IfModule mod_deflate.c> SetOutputFilter DEFLATE </IfModule> AuthUserFile /vol/httpd/htpasswd AuthName "" AuthType Basic Options +Indexes IndexOptions FancyIndexing Order Deny,Allow Allow from all Allow from localhost Allow from <IP address> </Location> <Directory /vol/webmanager/webmanager-webapps/webmanager-static-webapp/target/webmanager-static-webapp-10.9.0> Options +FollowSymLinks +includes AllowOverride All Require all granted </Directory> ProxyPass /web/ajp://localhost:19200/web/ ttl=600 ProxyPassReverse /web/ajp://localhost:19200/web/ <IfModule mod_rewrite.c> RewriteEngine On RewriteLogLevel 0 # Give not found on /web/admin/* on frontend url. RewriteCond %{REQUEST_URI}^/web/admin RewriteRule ^/web/admin - [R=404] RewriteCond %{REQUEST_URI} !^/web/ RewriteRule ^/(.*)\.htm$ /web/$1.htm [P,L] </IfModule> </VirtualHost>
HTTP/2 Support
Beginning with Apache Web server version 2.4.17, the HTTP/2 protocol is supported. Starting with version 10.12.0, XperienCentral is also tested on HTTP/2 over TLS. In principle, earlier 10.x versions of XperienCentral should also work over HTTP/2 but they have not been tested by GX Software.
Apache states on its website that the configuration of HTTP/2 is still an evolving process and that the mod_http2
module will continue to undergo improvements and tweaks and will change from version to version much more than the established modules. Keep this in mind when upgrading your Apache Web server.
In order to support HTTP/2, the Apache module mod_http2
must be loaded. HTTP/2 support is enabled by the following rule within mod_http2
:
# HTTP/2 Protocols h2 http/1.1
For more information on the mod_http2
module, see https://httpd.apache.org/docs/2.4/mod/mod_http2.html.
X-Frame Options
The following applies to XperienCentral versions 10.16.1 and higher.
Browsers have the possibility to restrict or deny loading a web-page inside a frame, iframe or object by reacting to the HTTP response header X-Frame-Options associated with this page. Setting this property can help in preventing click-jacking ( https://en.wikipedia.org/wiki/Clickjacking )
When setting this property there are three options:
- DENY - Indicates that this page may never be loaded inside another page.
- SAMEORIGIN - Indicates that this page may only be loaded inside another page if this page has the same origin
- ALLOW-FROM <origin> - Indicates that this page may only be loaded inside another page if this page is from the indicated origin, for example: www.mywebsite.com
It is not recommended to use the ALLOW-FROM option because it is not universally supported by all browsers.
In general you are advised to use this property with the option SAMEORIGIN to prevent click-jacking. For the front end environment you can also choose for the DENY option. Be aware that with that option pages can no longer be embedded in frames, iframes or other objects.
Configuring the Apache Http Server for X-Frame-Options is effective for both pages served by XperienCentral and external static pages.
Front-End Environment
Add the header for X-Frame-Options to the front-end environment (add in your .conf file):
<VirtualHost *:80> ServerName www.mywebsite.com ... Header always set X-Frame-Options SAMEORIGIN ... </VirtualHost>
Instead of SAMEORIGIN you can also specify DENY which will disable all embedding of pages into iframes, frames and other objects.
Backend Environment
Add the header for X-Frame-Options to the back end environment (internal edit environment of XperienCentral) (add in your .conf file):
<VirtualHost *:80> ServerName edit.mywebsite.com ... Header always set X-Frame-Options SAMEORIGIN ... </VirtualHost>
For the backend environment you cannot use DENY because XperienCentral itself uses frames.
Unpacking the XperienCentral Release
Before XperienCentral can be configured, the release has to be unpacked. To unpack the XperienCentral release, proceed as follows:
cd /vol/www/ mkdir webmanager-mywebsite cd webmanager-mywebsite unzip /tmp/GX_WebManager_x.x.x_SDK.zip
Modifying settings.xml
The XperienCentral configuration is set in settings.xml
. This file is located in the root of the unpacked XperienCentral release (/vol/www/webmanager-mywebsite/
). See JAVA_OPTS Parameters for more details and explanations on the JAVA_OPTS
settings..
Creating the Database(s)
XperienCentral data is stored in a relational database (MSSQL, MySQL, or Oracle). Create the databases desired for this installation. A complete XperienCentral installation requires only one database. In certain cases (performance/security), it is possible to save specific items in separate databases. A separate database can be created for the following components:
- XperienCentral core (JCR repository storage)
- XperienCentral other (externaldb)
The database for MySQL and MSSQL can be created with one single command and filled with the necessary tables. To create databases and the standard tables for Oracle, you have to use the standard Oracle tools (SQL Plus can be used, for instance). The initial scripts for all databases are: /vol/www/webmanager-mywebsite/webmanager-sqlscripts/
.
Actions for MySQL
cd /vol/www/webmanager-mywebsite mvn -s settings.xml -P create-mysql-db # If the content of JCR should be stored in another DB, then run: # mysqladmin create wm9mywebsite_jcr -u root -p
Actions for MSSQL
cd /vol/www/webmanager-mywebsite mvn -s settings.xml -P create-mssql-db # If the content of JCR should be stored in another DB, then # create the DB using the Enterprise Manager
Actions for Oracle
Start XperienCentral and create the database using the create-oracle-db
profile.
Installing the XperienCentral Release
The basic server setup is now complete. To install the release, proceed as follows:
cd /vol/www/webmanager-mywebsite mvn -s settings.xml -P configure-jcr-repository mvn -s settings.xml -P build-project cd /vol/www/mywebsite/ mkdir web-docs cd web-docs unzip /vol/www/webmanager-mywebsite/webmanager-webapps/\ webmanager-static-webapp/target/\ webmanager-static-webapp-1.0-SNAPSHOT.war # For JBoss use: # /vol/users/product/jboss/jboss-mywebsite/standalone/deployments cd /vol/www/tomcat-mywebsite/deploy cp /vol/www/webmanager-mywebsite/webmanager-webapps/appBase/\ webmanager-backend-webapp/target/\ webmanager-backend-webapp-1.0-SNAPSHOT.war . cd /vol/www/mywebsite/work/edition-bundles cp /vol/www/webmanager-mywebsite/edition-bundles/*.jar . cd /vol/www/mywebsite/system/ cp /vol/www/webmanager-mywebsite/settings.xml . cp /vol/www/webmanager-mywebsite/webmanager-cleansite/target/\ webmanager-cleansite-1.0-SNAPSHOT.jar . rm /tmp/GX_WebManager_10.10.0_SDK.zip
Configuring Tomcat
For Tomcat, two files need to be created. Place these files in the /vol/www/tomcat-mywebsite/conf
directory.
The conf/server.xml for HTTP
<Server port="8005" shutdown="SHUTDOWN"> <GlobalNamingResources> <!-- Userdatabase is used to secure admin pages! Make sure the path is ok otherwise the admin jsps will not work --> <Resource name="WMUserDatabase" auth="Container" type="org.apache.catalina.UserDatabase" description="XperienCentral user database" factory="org.apache.catalina.users.MemoryUserDatabaseFactory" pathname="/vol/www/tomcat-mywebsite/deploy/admin-users.xml" /> </GlobalNamingResources> <Service name="WebManager"> <Connector port="8009" enableLookups="false" redirectPort="8443" debug="1" protocol="AJP/1.3" URIEncoding="UTF-8" connectionTimeout="600000"/> <Engine name="WebManager" defaultHost="localhost"> <Realm className="org.apache.catalina.realm.LockOutRealm" > <Realm className="org.apache.catalina.realm.UserDatabaseRealm" resourceName="WMUserDatabase"/> </Realm> <Host name="localhost" unpackWARs="true" autoDeploy="false" deployOnStartup="false" appBase="/vol/www/tomcat-mywebsite/deploy"> <Valve className="org.apache.catalina.authenticator.SingleSignOn" /> <Context path="/web" docBase="webmanager-backend-webapp-1.0-SNAPSHOT.war"> <Valve className="org.apache.catalina.authenticator.DigestAuthenticator" cache="true" /> </Context> </Host> </Engine> </Service> </Server>
The conf/server.xml for HTTPS
<Server port="8005" shutdown="SHUTDOWN"> <GlobalNamingResources> <!-- Userdatabase is used to secure admin pages! Make sure the path is ok otherwise the admin jsps will not work --> <Resource name="WMUserDatabase" auth="Container" type="org.apache.catalina.UserDatabase" description="XperienCentral user database" factory="org.apache.catalina.users.MemoryUserDatabaseFactory" pathname="/vol/www/tomcat-mywebsite/deploy/admin-users.xml" /> </GlobalNamingResources> <Service name="WebManager"> <Connector port="8009" enableLookups="false" debug="1" protocol="AJP/1.3" URIEncoding="UTF-8" connectionTimeout="600000"/> <Engine name="WebManager" defaultHost="localhost"> <Realm className="org.apache.catalina.realm.LockOutRealm" > <Realm className="org.apache.catalina.realm.UserDatabaseRealm" resourceName="WMUserDatabase"/> </Realm> <Host name="localhost" unpackWARs="true" autoDeploy="false" deployOnStartup="false" appBase="/vol/www/tomcat-mywebsite/deploy"> <Valve className="org.apache.catalina.authenticator.SingleSignOn" /> <Context path="/web" docBase="webmanager-backend-webapp-1.0-SNAPSHOT.war"> <Valve className="org.apache.catalina.authenticator.DigestAuthenticator" cache="true" /> </Context> </Host> </Engine> </Service> </Server>
The conf/admin-users.xml
<?xml version='1.0' encoding='utf-8'?> <tomcat-users> <role rolename="wmadmin"/> <user username="wmadmin_user" password="MyPassword" roles="wmadmin"/> </tomcat-users>
The conf/context.xml
<?xml version='1.0' encoding='utf-8'?> <Context sessionCookiePath="/"> <WatchedResource>WEB-INF/web.xml</WatchedResource> </Context>
The JDBC Drivers
The JDBC Drivers have to be copied to the /vol/www/tomcat-mywebsite/lib
directory:
cd /vol/www/tomcat-mywebsite/lib cp /vol/www/webmanager-mywebsite/ext/jtds-1.3.1.jar cp /vol/www/webmanager-mywebsite/ext/mysql-connector-java-5.1.23 cp /vol/www/webmanager-mywebsite/ext/oraclejdbcdriver-11.2.0.2.0
Server.xml Configuration
For the supported databases, you must add the JDBC resource to the XperienCentral server.xml
:
Oracle
<!-- ORACLE --> <Resource name="jdbc/WebManagerDb" auth="Container" type="javax.sql.DataSource" username="CHANGEME" password="CHANGEME" driverClassName="oracle.jdbc.driver.OracleDriver" url="jdbc:oracle:thin:@SERVERNAME:PORTNR:INSTANCE" maxActive="100" maxIdle="10" maxWait="10000" testWhileIdle="true" timeBetweenEvictionRunsMillis="900000" removeAbandoned="true" removeAbandonedTimeout="30" logAbandoned="true" validationQuery="SELECT 1 FROM DUAL"/>
MSSQL
<!-- MSSQL --> <Resource name="jdbc/WebManagerDb" auth="Container" type="javax.sql.DataSource" username="CHANGEME" password="CHANGEME" driverClassName="net.sourceforge.jtds.jdbc.Driver" url="jdbc:jtds:sqlserver://SERVERNAME:PORTNR/INSTANCE" maxActive="40" maxIdle="1" maxWait="10000" testWhileIdle="true" timeBetweenEvictionRunsMillis="900000" removeAbandoned="true" removeAbandonedTimeout="30" logAbandoned="true" poolPreparedStatements="true"
MySQL
<!-- MYSQL --> <Resource name="jdbc/WebManagerDb" auth="Container" type="javax.sql.DataSource" username="CHANGEME" password="CHANGEME" driverClassName="com.mysql.jdbc.Driver" url="jdbc:mysql://SERVERNAME:PORTNR/INSTANCE?autoReconnect=true" maxActive="100" maxIdle="10" maxWait="10000" testWhileIdle="true" timeBetweenEvictionRunsMillis="900000" removeAbandoned="true" removeAbandonedTimeout="30" logAbandoned="true" validationQuery="SELECT 1" maxOpenPreparedStatements="100" />
Support for Special Characters
If you use special characters in file names, add the following to setenv.sh
:
export LANG=en_US.utf8
Backend Container Authentication
XperienCentral supports the trusting of the authentication of users in a backend container which in turn means that they do not have to supply a username/password combination when they log in to XperienCentral. See Backend Container-based Authentication for complete information.
Configuring JBoss
Perform the configuration steps as described below.
Make the Database Driver Available
Obtain a copy of the database driver from the Maven repository. Copy the driver for your database to the directory jboss-mywebsite/modules/system/layers/base
. Use the following JAR files for the following databases:
- For MSSQL, copy
jtds-1.3.1.jar
tonet/sourceforge/jtds/main
. - For MySQL, copy
mysql-connector-java-5.1.23.jar
tocom/mysql/main
. - For Oracle, copy
oraclejdbcdriver-12.1.0.2.jar
tooracle/oraclejdbcdriver/main
.
In the main directory, create a file named module.xml with the following content:
MSSQL
<?xml version="1.0" encoding="UTF-8"?> <module xmlns="urn:jboss:module:1.1" name="net.sourceforge.jtds"> <resources> <resource-root path="jtds-1.3.1.jar"/> </resources> <dependencies> <module name="javax.api"/> <module name="javax.transaction.api"/> </dependencies> </module>
MySQL
<?xml version="1.0" encoding="UTF-8"?> <module xmlns="urn:jboss:module:1.1" name="com.mysql"> <resources> <resource-root path="mysql-connector-java-5.1.23.jar"/> </resources> <dependencies> <module name="javax.api"/> <module name="javax.transaction.api"/> </dependencies> </module>
Oracle
<?xml version="1.0" encoding="UTF-8"?> <module xmlns="urn:jboss:module:1.1" name="oracle.oraclejdbcdriver"> <resources> <resource-root path="oraclejdbcdriver-12.1.0.2.jar"/> </resources> <dependencies> <module name="javax.api"/> <module name="javax.transaction.api"/> </dependencies> </module>
Reference the database driver in standalone/configuration/standalone.xml
within the jboss:domain:datasources subsystem
:
For MSSQL
<driver name="JTDS" module="net.sourceforge.jtds"> <driver-class>net.sourceforge.jtds.jdbc.Driver</driver-class> </driver>
For MySQL
<driver name="MYSQL" module="com.mysql"> <driver-class>com.mysql.jdbc.Driver</driver-class> </driver>
For Oracle
<driver name="ORACLE" module="oracle.oraclejdbcdriver"> <driver-class>oracle.jdbc.OracleDriver</driver-class> </driver>
Add All Relevant Data Sources to standalone.xml within the jboss:domain:datasources Subsystem
<datasource jndi-name="java:jboss/jdbc/WebManagerDb" pool-name="WebManagerDb" enabled="true" use-java-context="true"> <connection-url>{connectionurl}</connection-url> <driver>{drivername}</driver> <security> <user-name>{username}</user-name> <password>{password}</password> </security> </datasource>
In the XML above, replace {connectionurl}
, {username}
, and {password}
with the appropriate values. The driver name must be either JTDS
, MYSQL
, or ORACLE
(the value of the name attribute of the driver reference). Example connection URLs:
MSSQL: jdbc:jtds:sqlserver://mydomain:2433/webmanager9181;useLOBs=false
MySQL: jdbc:mysql://mydomain:3306/webmanager9181?autoReconnect=true
Oracle: jdbc:oracle:thin:@mydomain:1521:xe
Disable the Default Welcome Root Web Application
In standalone.xml
, set enable-welcome-root
to false
for the virtual-server name:
<virtual-server name="default-host" enable-welcome-root="false">
Add Aliases for Hostnames
In standalone.xml
, add the aliases for the hostnames you are using:
<virtual-server name="default-host" enable-welcome-root="false"> <alias name="mydomain.mycompany.com"/> <alias name="myalias"/> </virtual-server>
Enable the AJP Connector
<connector name="http" protocol="HTTP/1.1" scheme="http" socket-binding="http" /> <connector name="ajp" protocol="AJP/1.3" scheme="http" socket-binding="ajp"/>
Enable the wmadmin Login
In standalone.xml
, add the XperienCentral security domain. This is necessary because the XperienCentral file jboss-web.xml
references the XperienCentral security domain
<security-domain name="GX-WebManager" cache-type="default"> <authentication> <login-module code="UsersRoles" flag="required"> <module-option name="usersProperties" value="${jboss.server.config.dir}/users.properties"/> <module-option name="rolesProperties" value="${jboss.server.config.dir}/roles.properties"/> <module-option name="hashAlgorithm" value="MD5"/> <module-option name="hashEncoding" value="RFC2617"/> <module-option name="hashUserPassword" value="false"/> <module-option name="hashStorePassword" value="true"/> <module-option name="passwordIsA1Hash" value="true"/> <module-option name="storeDigestCallback" value="org.jboss.security.auth.callback.RFC2617Digest"/> </login-module> </authentication> </security-domain>
Adjust the Deployment Timeout
In standalone.xml
, add the deployment timeout tag to the deployment-scanner
path:
<subsystem xmlns="urn:jboss:domain:deployment-scanner:1.1"> <deployment-scanner path="deployments" relative-to="jboss.server.base.dir" scan-interval="5000" deployment-timeout="1000"/>
Generate and Store the JBoss 6.3.3 EAP Application Server Hash
cd /vol/www/jboss-cleansite/bin/client
/usr/local/java8/bin/java -cp jboss-cli-client.jar org.jboss.security.auth.callback.RFC2617Digest wmadmin "XperienCentral" <password>
Store the generated hash:
echo "wmadmin=<generated_hash>" > jboss-mywebsite/standalone/configuration/users.properties echo "wmadmin=wmadmin" > jboss-mywebsite/standalone/configuration/roles.properties
Backend Container Authentication
XperienCentral supports the trusting of the authentication of users in a backend container which in turn means that they do not have to supply a username/password combination when they log in to XperienCentral. See Backend Container Authentication for complete information.
Placing the configuration.xml
Place configuration.xml
in the /vol/www/mywebsite/configuration/
directory.
Setting Permissions Correctly
During installation, the root account is used. After installation, it is recommended that you attach permissions to certain directories, for example, Tomcat runs under the user/group tomcat/www
and Aache runs under the user/group apache/www
. New users can be created with the adduser
command. New groups can be created with the groupadd
command. Assuming the above directory structure, users, and groups, the following UNIX commands can be used:
# Change the permissions for the Tomcat directory cd /vol/www/tomcat-mywebsite chown -R tomcat:www deploy logs work temp chmod -R guo+r . # Modify the webdirectory’s settings cd /vol/www/mywebsite chown -R tomcat:www . chmod -R guo+r .
Make the Hostnames Resolvable
The server on which XperienCentral is installed needs to be able to resolve the hostnames that are used for the edit environment and the external environment of XperienCentral. In the example the hostnames are www.mywebsite.com
and edit.mywebsite.com
. Add the used hostnames to the file /etc/hosts
if the used hostnames don’t resolve to the right IP address on the server.
Setting up rc Scripts
All files are now ready and configured correctly: the application server (Tomcat or JBoss) and Apache can be started. Make sure that the GX search engine (if necessary), database, application server, and Apache automatically start after a system reboot. Make sure that in the rc scripts for the application server the directories are being removed that are temporary for the application server, before XperienCentral is started.
In the case of Tomcat, these directories are:
- Tomcat’s
work
directory - The
osgi
directory - The
deploy/appBase
directory - Tomcat’s
temp
directory
For JBoss, empty the next folder before each start:
- The
/vol/www/mywebsite/work/osgi
directory
To start a JBoss Enterprise Application Platform 6 Standalone Server (a single server instance), use the command:
/vol/www/jboss-mywebsite/bin/standalone.sh –b edit.mywebsite.com –c webmanager
To start a JBoss Enterprise Application Platform 6 Managed Domain, which allows control and management of multiple instances, use the command:
/vol/www/jboss-mywebsite/bin/domain.sh –b edit.mywebsite.com –c webmanager
Configure the Apache PDFBox Cache Directory
XperienCentral uses the Apache PDFBox library for working with PDF documents. In order for the library to function correctly, you need to configure the directory it uses for caching. To do so set the pdfbox.fontcache
system property to use the Java tmp
directory. Be sure that XperienCentral has sufficient rights to write to the tmp
directory
Controlling the Startup Block Mechanism
By default, XperienCentral blocks login requests from the front-end and back-end while it is starting up. If XperienCentral receives a request for a page from either the frontend or backend during the startup sequence between the time that the log messages Server startup in <x> ms
and XperienCentral started successfully in <x> ms
appear, the following message will appear in the browser:
To block this message, add the following JAVA_OPTS
property to the beginning of the XperienCentral block:
-Dwebmanager.startupblock.skip=true
For example:
set JAVA_OPTS=%JAVA_OPTS% -Dwebmanager.startupblock.skip=true -Djava.awt.headless=true -Dwebmanager.jcr.filemirror=true -Dwebmanager.clustering.readonly=false -Xms512m -Xmx512m –Xdebug
-Xrunjdwp:transport=dt_socket,server=y,suspend=n,address=8000
When blocking is turned off, requests from the frontend will return a cached version of the requested page or a white page with no content when XperienCentral has not finished the startup process. Requests from the backend will show the XperienCentral login screen, however you will not be able to log in.
To turn blocking back on, change the ‘true’ declaration to false
. For example:
-Dwebmanager.startupblock.skip=false