Production Deployment Guidelines

The requirements for deploying WSO2 products can change based on the deployment scenario and pattern used. The recommendations in this topic are for general production use, assuming moderate load conditions. For situations where a high volume of traffic is expected and larger deployments, these guidelines may not be sufficient. See Troubleshooting in Production Environments for information on how to obtain and analyze information to solve production issues. The following are the topics addressed in this section.

Installation prerequisites

Prior to installing any WSO2 Carbon-based product, it is necessary to have the appropriate hardware and software necessary for running the product.

Hardware requirements (per WSO2 product instance)

Environment compatibility

• All WSO2 Carbon-based products are Java applications that can be run on any platform that is Oracle JDK 1.6.*/1.7.* compliant. JDK 1.8 is not supported yet. Also OpenJDK is not recommended or supported. 
• All WSO2 Carbon-based products are generally compatible with most common DBMSs. For more information, see Working with Databases.
• It is not recommended to use Apache DS in a production environment due to issues with scalability. Instead, it is recommended to use an LDAP like OpenLDAP for user management.

• On a production deployment, it is recommended that WSO2 products are installed on latest releases of RedHat Enterprise Linux or Ubuntu Server LTS.

• For environments that WSO2 products are tested with, see Environments Tested with WSO2 Products. 
• If you have difficulty in setting up any WSO2 product in a specific platform or database, please contact us.

Required applications

The following applications are required for running the WSO2 product and its samples or for building from the source code. Mandatory installs are marked with *.

You are now ready to install the WSO2 product.

Installing the WSO2 product

Do the following to install the WSO2 product.

1. If you have not done so already, download the latest version of the WSO2 product from the product section of wso2.com.
   
   

2. Extract the archive file to a dedicated directory for the WSO2 product. This will hereafter be referred to as <PRODUCT_HOME> in this guide.

Setting JAVA_HOME

You must set your JAVA_HOME environment variable to point to the directory where the Java Development Kit (JDK) is installed on the computer.

1. In your home directory, open the BASHRC file (.bash_profile file
 on OS X) in a Linux text editor, such as vi, emacs, pico, or mcedit.

2. Add the following two lines at the bottom of the file, replacing /usr/java/jdk1.6.0_25 with the actual directory where the JDK is installed.

   On Linux:
   export JAVA_HOME=/usr/java/jdk1.6.0_25
   export PATH=${JAVA_HOME}/bin:${PATH}
    
   On OS X:
   export JAVA_HOME=/System/Library/Java/JavaVirtualMachines/1.6.0.jdk/Contents/Home

   In Linux, the file should now look like this:
   

3. Save the file.

   If you do not know how to work with text editors in a Linux SSH session, run the following command:

   cat >> .bashrc

   Paste the string from the clipboard and press "Ctrl+D".

4. To verify that the JAVA_HOME variable is set correctly, execute the following command:

   On Linux:
   echo $JAVA_HOME
    
   On OS X:
   which java
    
   If the above command gives you a path like /usr/bin/java, then it is a symbolic link to the real location. To get the real location, run the following:
   ls -l `which java`

   The system returns the JDK installation path.

Setting system properties

If you need to set additional system properties when the server starts, you can take the following approaches:

• Set the properties from a script. Setting your system properties in the startup script is ideal, because it ensures that you set the properties every time you start the server. To avoid having to modify the script each time you upgrade, the best approach is to create your own startup script that wraps the WSO2 startup script and adds the properties you want to set, rather than editing the WSO2 startup script directly.
  Set the properties from an external registry. If you want to access properties from an external registry, you could create Java code that reads the properties at runtime from that registry. Be sure to store sensitive data such as username and password to connect to the registry in a properties file instead of in the Java code and secure the properties file with the secure vault.

You are now ready to run the product.

Running the product

To run WSO2 products, you start the product server at the command line. You can then run the Management Console application to configure and manage the product. Before you start the server, note the following:

• The config-validation.xml file in the <PRODUCT_HOME>/repository/conf/etc directory contains a list of recommended system parameters, which are validated against your system when the server starts. See Configuring config-validation.xml for details on modifying these parameters before starting the server.
• The Management Console uses the default HTTP-NIO transport, which is configured in the catalina-server.xml file in the <PRODUCT_HOME>/repository/conf/tomcat directory. This transport must be properly configured in this file for the Management Console to be accessible.

Starting the server

To start the server, you run the script wso2server.sh (on Linux) from the bin folder.

1. Open the command line on Linux and establish a SSH connection to the server or log into the text Linux console.

2. Execute the following command, where <PRODUCT_HOME> is the directory where you installed the product distribution:

   sh <PRODUCT_HOME>/bin/wso2server.sh

   If you want to provide access to the production environment without allowing any user group (including admin) to log into the management console, execute the following command.
   sh <PRODUCT_HOME>/bin/wso2server.sh -DworkerNode

   If you want to check any additional options available to be used with the startup commands, type -help after the command, such as: sh <PRODUCT_HOME>/bin/wso2server.sh -help.

   Alternatively, you can restrict access to the management console of your product by binding the management console with selected IP addresses. Note that you can either restrict access to the management console only, or you can restrict access to all web applications in your server as explained below.

   • To control access only to the management console, add the IP addresses to the <PRODUCT_HOME>/repository/conf/tomcat/carbon/META-INF/context.xml file as follows:
     

     <Valve className="org.apache.catalina.valves.RemoteAddrValve" allow="<IP-address-01>|<IP-address-02>|<IP-address-03>"/>

     The RemoteAddrValve Tomcat valve defined in this file will only apply to the Carbon management console, and thereby all outside requests to the management console will be blocked. 

   • To control access to all web applications deployed in your server, add the IP addresses to the <PRODUCT_HOME>/repository/conf/context.xml file as follows:
     

     <Valve className="org.apache.catalina.valves.RemoteAddrValve" allow="<IP-address-01>|<IP-address-02>|<IP-address-03>"/>

     The RemoteAddrValve Tomcat valve defined in this file will apply to each web application hosted on the Carbon server. Therefore, all outside requests to any web application will be blocked.
     

   • You can also restrict access to particular servlets in a web application by adding a Remote Address Filter to the web.xml file (stored in the <PRODUCT_HOME>/repository/conf/tomcat/ directory), and by mapping that filter to the servlet url. In the Remote Address Filter that you add, you can specify the IP addresses that should be allowed to access the servlet.

     
     The following example from a web.xml file illustrates how access to the management page (/carbon/admin/login.jsp) is granted only to one IP address:
     

     <filter>
         <filter-name>Remote Address Filter</filter-name>
         <filter-class>org.apache.catalina.filters.RemoteAddrFilter</filter-class>
             <init-param>
                 <param-name>allow</param-name>
                 <param-value>127.0.01</param-value>
             </init-param>
     </filter>
     
     <filter-mapping>
         <filter-name>Remote Address Filter</filter-name>
         <url-pattern>/carbon/admin/login.jsp</url-pattern>
     </filter-mapping>

   Note: Any configurations (including valves) defined in the <PRODUCT_HOME>/repository/conf/tomcat/catalina-server.xml file applies to all web applications and is globally available across server, regardless of host or cluster. See the official Tomcat documentation for more information about using remote host filters.

   The operation log appears. When the product server is running, the log displays the message "WSO2 Carbon started in 'n' seconds."

Stopping the server

To stop the server, press Ctrl+C in the command window, or click the Shutdown/Restart link in the navigation pane in the Management Console.

Running recommendations for security

The following are security related recommendations to be followed when running the product.

• Running as a different user: For security reasons, it's recommended to run the product as an unprivileged user. After adding a user to the system, apply your organizational security policies to that user.
• Running on a different port: If you want to run on a different port, like port 80, the recommended way is to add a port forwarding rule from your firewall.
• Running as a Unix daemon: You have the option of running each product as a standard Unix service. You can start, stop and restart the WSO2 product instances as follows.
  # sh bin/wso2server.sh [start | stop | restart]

Host machine security hardening

Integrate the newly added server to your organizational backup policy of critical services. This will help you to recover a critical system in case of a compromise. We recommend you apply all the critical security patches from the respective OS vendor. If you have RedHat Enterprise Linux installed you must have a RHN subscription to receive updates. Turning off all services that you're not using is also critical. You can further add a firewall rule to close all ports other than the ports the WSO2 product is running on.

The following links give some sample guidelines on server hardening:

• http://www.puschitz.com/SecuringLinux.shtml

• http://www.tecmint.com/linux-server-hardening-security-tips/

Common guidelines and checklist

The following table lists out the common guidelines and details pertaining to them. These are common to all products and are followed for making an installed WSO2 product ready for production.

-Xms512m -Xmx2048m -XX:MaxPermSize=1024m

<HostName>your.host.name</HostName>

<parameter name="WSDLEPRPrefix" locked="false">[http]://your.host.name:[port]</parameter>

<Ports>
	<JMX>9999</JMX>
</Ports>

-Dhttp.proxyHost=xxxx 
-Dhttp.proxyPort=xxxx

<parameter name="Proxy">
    <Configuration>
    <proxyhost>you.proxy.host</proxyhost>
    <proxyport>your.proxy.port</proxyport>
    </configuration>
</parameter>

log4j.appender.CARBON_LOGFILE=org.apache.log4j.RollingFileAppender
log4j.appender.CARBON_LOGFILE=${carbon.home}/repository/logs/${instance.log}/wso2carbon${instance.log}.log
log4j.appender.CARBON_LOGFILE.MaxFileSize=1000KB
log4j.appender.CARBON_LOGFILE.MaxBackupIndex=10