=================================================================================

  Copyright (c) 2016, WSO2 Inc. (http://www.wso2.org) All Rights Reserved.

  WSO2 Inc. licenses this file to you under the Apache License,
  Version 2.0 (the "License"); you may not use this file except
  in compliance with the License.
  You may obtain a copy of the License at

  http://www.apache.org/licenses/LICENSE-2.0

  Unless required by applicable law or agreed to in writing,
  software distributed under the License is distributed on an
  "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
  KIND, either express or implied. See the License for the
  specific language governing permissions and limitations
  under the License.

================================================================================

            =========================================
            Running The WSO2 Application Server 6.0.0
            =========================================

WSO2 Application Server 6.0.0 requires a Java Standard Edition Runtime
Environment (JRE) version 8 or later.

=============================
Running With JRE 8 Or Later
=============================

(1) Download and Install a Java SE Runtime Environment (JRE)

(1.1) Download a Java SE Runtime Environment (JRE),
      release version 8 or later, from
      http://www.oracle.com/technetwork/java/javase/downloads/index.html

(1.2) Install the JRE according to the instructions included with the
      release.

      You may also use a full Java Development Kit (JDK) rather than just
      a JRE.


(2) Download and Install WSO2 Application Server

(2.1) Download a binary distribution of WSO2 Application Server from:

      http://wso2.com/products/application-server/

(2.2) Unpack the binary distribution so that it resides in its own
      directory (conventionally named "wso2as-[version]").

      For the purposes of the remainder of this document, the name
      "CATALINA_HOME" is used to refer to the full pathname of that
      directory.

NOTE:  As an alternative to downloading a binary distribution, you can
create your own from the Appication Server source code.


(3) Configure Environment Variables

WSO2 Application Server is a Java application and does not use environment variables. The
variables are used by the WSO2 Application Server startup scripts. The scripts use the variables
to prepare the command that starts WSO2 Application Server.

(3.1) Set CATALINA_HOME (required) and CATALINA_BASE (optional)

The CATALINA_HOME environment variable should be set to the location of the
root directory of the "binary" distribution of WSO2 Application Server.

An example was given in (2.2) above.

The WSO2 Application Server startup scripts have some logic to set this variable
automatically if it is absent, based on the location of the startup script
in *nix and on the current directory in Windows. That logic might not work
in all circumstances, so setting the variable explicitly is recommended.

The CATALINA_BASE environment variable specifies location of the root
directory of the "active configuration" of WSO2 Application Server. It is optional. It
defaults to be equal to CATALINA_HOME.

Using distinct values for the CATALINA_HOME and CATALINA_BASE variables is
recommended to simplify further upgrades and maintenance. It is documented
in the "Multiple WSO2 Application Server Instances" section below.


(3.2) Set JRE_HOME or JAVA_HOME (required)

These variables are used to specify location of a Java Runtime
Environment or of a Java Development Kit that is used to start WSO2 Application Server.

The JRE_HOME variable is used to specify location of a JRE. The JAVA_HOME
variable is used to specify location of a JDK.

Using JAVA_HOME provides access to certain additional startup options that
are not allowed when JRE_HOME is used.

If both JRE_HOME and JAVA_HOME are specified, JRE_HOME is used.

The recommended place to specify these variables is a "setenv" script. See
below.


(3.3) Other variables (optional)

Other environment variables exist, besides the four described above.
See the comments at the top of catalina.bat or catalina.sh scripts for
the list and a description of each of them.

One frequently used variable is CATALINA_OPTS. It allows specification of
additional options for the java command that starts WSO2 Application Server.

See the Java documentation for the options that affect the Java Runtime
Environment.

See the "System Properties" page in the WSO2 Application Server Configuration Reference for
the system properties that are specific to WSO2 Application Server.

A similar variable is JAVA_OPTS. It is used less frequently. It allows
specification of options that are used both to start and to stop WSO2 Application Server as well
as for other commands.

Note: Do not use JAVA_OPTS to specify memory limits. You do not need much
memory for a small process that is used to stop WSO2 Application Server. Those settings
belong to CATALINA_OPTS.

Another frequently used variable is CATALINA_PID (on *nix only). It
specifies the location of the file where process id of the forked WSO2 Application Server
java process will be written. This setting is optional. It will enable the
following features:

 *  better protection against duplicate start attempts and
 *  allows forceful termination of WSO2 Application Server process when it does not react to
    the standard shutdown command.



(4) Start Up the WSO2 Application Server

(4.1) WSO2 Application Server can be started by executing one of the following commands:

  On Windows:

      %CATALINA_HOME%\bin\catalina.bat start

  On *nix:

      $CATALINA_HOME/bin/catalina.sh start

(4.2) After startup, the default web applications included with WSO2 Application Server will be
      available by visiting:

      http://localhost:8080/

(4.3) Further information about configuring and running WSO2 Application Server can be found in
      the documentation web site:

      https://docs.wso2.com/display/AS600/


(5) Shut Down the WSO2 Application Server

(5.1) WSO2 Application Server can be shut down by executing one of the following commands:

  On Windows:

      %CATALINA_HOME%\bin\catalina.bat stop

  On *nix:

      $CATALINA_HOME/bin/catalina.sh stop

===================================================================
Advanced Configuration - Multiple WSO2 Application Server Instances
===================================================================

In many circumstances, it is desirable to have a single copy of a WSO2 Application Server
binary distribution shared among multiple users on the same server.  To make
this possible, you can set the CATALINA_BASE environment variable to the
directory that contains the files for your 'personal' WSO2 Application Server instance.

See tomcat guide for more information https://tomcat.apache.org/tomcat-8.0-doc/RUNNING.txt


================
Troubleshooting
================

There are only really 2 things likely to go wrong during the stand-alone
WSO2 Application Server install:

(1) The most common hiccup is when another web server (or any process for that
    matter) has laid claim to port 8080.  This is the default HTTP port that
    WSO2 Application Server attempts to bind to at startup.  To change this, open the file:

       $CATALINA_HOME/conf/server.xml

    and search for '8080'.  Change it to a port that isn't in use, and is
    greater than 1024, as ports less than or equal to 1024 require superuser
    access to bind under UNIX.

    Restart WSO2 Application Server and you're in business.  Be sure that you replace the "8080"
    in the URL you're using to access WSO2 Application Server.  For example, if you change the
    port to 1977, you would request the URL http://localhost:1977/ in your
    browser.

(2) The 'localhost' machine isn't found.  This could happen if you're behind a
    proxy.  If that's the case, make sure the proxy configuration for your
    browser knows that you shouldn't be going through the proxy to access the
    "localhost".

    In Firefox, this is under Tools/Preferences -> Advanced/Network ->
    Connection -> Settings..., and in Internet Explorer it is Tools ->
    Internet Options -> Connections -> LAN Settings.


====================
Optional Components
====================

The following optional components may be included with the WSO2 Application Server binary
distribution. If they are not included, you can install them separately.

 1. Apache Tomcat Native library

 2. Apache Commons Daemon service launcher

Both of them are implemented in C language and as such have to be compiled
into binary code. The binary code will be specific for a platform and CPU
architecture and it must match the Java Runtime Environment executables
that will be used to launch WSO2 Application Server.

The Windows-specific binary distributions of WSO2 Application Server include binary
files for these components. On other platforms you would have to look for
binary versions elsewhere or compile them yourself.

If you are new to WSO2 Application Server, do not bother with these components to start with.
If you do use them, do not forget to read their documentation.


Apache Tomcat Native library
-----------------------------

It is a library that allows to use the "Apr" variant of HTTP and AJP
protocol connectors in Apache Tomcat. It is built around OpenSSL and Apache
Portable Runtime (APR) libraries. Those are the same libraries as used by
Apache HTTPD Server project.

This feature was especially important in the old days when Java performance
was poor. It is less important nowadays, but it is still used and respected
by many. See Tomcat documentation for more details.

For further reading:

 - Apache Tomcat documentation

    * Documentation for APR/Native library in the Tomcat User's Guide

      http://tomcat.apache.org/tomcat-8.0-doc/apr.html

    * Documentation for the HTTP and AJP protocol connectors in the Tomcat
      Configuration Reference

      http://tomcat.apache.org/tomcat-8.0-doc/config/http.html

      http://tomcat.apache.org/tomcat-8.0-doc/config/ajp.html

 - Apache Tomcat Native project home

      http://tomcat.apache.org/native-doc/

 - Other projects

    * OpenSSL

      http://openssl.org/

    * Apache Portable Runtime

      http://apr.apache.org/

    * Apache HTTP Server

      http://httpd.apache.org/

To disable Apache Tomcat Native library:

 - To disable Apache Tomcat Native library when it is installed, or
 - To remove the warning that is logged during Tomcat startup when the
   library is not installed:

   Edit the "conf/server.xml" file and remove "AprLifecycleListener" from
   it.

The binary file of Apache Tomcat Native library is usually named

  - "tcnative-1.dll" on Windows
  - "libtcnative-1.so" on *nix systems


Apache Commons Daemon
----------------------

Apache Commons Daemon project provides wrappers that can be used to
install Apache Tomcat as a service on Windows or as a daemon on *nix
systems.

The Windows-specific implementation of Apache Commons Daemon is called
"procrun". The *nix-specific one is called "jsvc".

For further reading:

 - Apache Commons Daemon project

      http://commons.apache.org/daemon/

 - Apache Tomcat documentation

    * Installing Apache Tomcat

      http://tomcat.apache.org/tomcat-8.0-doc/setup.html

    * Windows service HOW-TO

      http://tomcat.apache.org/tomcat-8.0-doc/windows-service-howto.html

The binary files of Apache Commons Daemon in Apache Tomcat distributions
for Windows are named:

  - "tomcat8.exe"
  - "tomcat8w.exe"

These files are renamed copies of "prunsrv.exe" and "prunmgr.exe" from
Apache Commons Daemon distribution. The file names have a meaning: they are
used as the service name to register the service in Windows, as well as the
key name to store distinct configuration for this installation of
"procrun". If you would like to install several instances of Tomcat 8.0
in parallel, you have to further rename those files, using the same naming
scheme.
