geode-docs/tools_modules/http_session_mgmt/quick_start.html.md.erb - geode - Git at Google

 ---
 title:  HTTP Session Management Quick Start
 ---

 <!--
 Licensed to the Apache Software Foundation (ASF) under one or more
 contributor license agreements.  See the NOTICE file distributed with
 this work for additional information regarding copyright ownership.
 The ASF 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.
 -->

 In this section you download, install, and set up the HTTP Session Management modules.

 ## <a id="quick_start__section_6A4A00B6DA404E10A5C29E5E31101445" class="no-quick-link"></a>Quick Start Instructions

 1.  Download and install one of the application servers.

     | Supported Application Server | Version                     | Download Location                                                                                                                                                                                                    |
     |------------------------------|-----------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
     | tc Server                    | 3.2           | [https://network.pivotal.io/products/pivotal-tcserver](https://network.pivotal.io/products/pivotal-tcserver)                                                                     |
     | Tomcat                       | 8.5                    | [http://tomcat.apache.org/download-80.cgi](http://tomcat.apache.org/download-80.cgi)                                                                                             |
     | Tomcat                       | 9.0                    | [https://tomcat.apache.org/download-90.cgi](https://tomcat.apache.org/download-90.cgi)                                                                                             |

     The generic HTTP Session Management Module for AppServers is implemented as a servlet filter and should work on any application server platform that supports the Java Servlet 3.1 specification.

 2.  The HTTP Session Management Modules installation .zip files are located in the `tools/Modules` directory of the product installation directory. Locate the .zip file for the HTTP Session Management Module that you wish to install. Unzip the appropriate HTTP Session Management Module into the specified directory for your application server:

     | Supported Application Server | Version                     | Module                                                   | Target Location for Module                                                       |
     |------------------------------|-----------------------------|----------------------------------------------------------|----------------------------------------------------------------------------------|
     | tc Server                    | 3.2           | HTTP Session Management Module for Pivotal tc Server     | `<tc Server root                                                 dir>/templates` |
     | Tomcat                       | 8.5            | HTTP Session Management Module for Tomcat                | `$CATALINA_HOME`                                                                 |
     | Tomcat                       | 9.0            | HTTP Session Management Module for Tomcat                | `$CATALINA_HOME`                                                                 |

 3.  Complete the appropriate set up instructions for your application server described in the following sections:
     -   [Additional Quick Start Instructions for tc Server Module](quick_start.html#quick_start__section_EE60463F524A46B7B83CE74C1C3E8E0E)
     -   [Additional Quick Start Instructions for Tomcat Module](quick_start.html#quick_start__section_4689A4FA609A4F4FB091F03E9BECA4DB)
     -   [Additional Instructions for AppServers Module](quick_start.html#quick_start__section_1587C3E55F06406EBD4AB13014A406D4)

 ## <a id="quick_start__section_EE60463F524A46B7B83CE74C1C3E8E0E" class="no-quick-link"></a>Additional Quick Start Instructions for tc Server Module

 These steps provide a basic starting point for using the tc Server module. For more configuration options, see [HTTP Session Management Module for Pivotal tc Server](session_mgmt_tcserver.html). As a prerequisite, module set up requires a JAVA\_HOME environment variable set to the java installation.

 1.  Navigate to the root directory of tc Server.
 2.  Create a <%=vars.product_name%> instance using one of the provided templates and start the instance after starting up a locator. For example:

     ``` pre
     $ gfsh start locator --name=locator1
     $ ./tcruntime-instance.sh create my_instance_name --template geode-p2p
     $ ./tcruntime-ctl.sh my_instance_name start
     ```

     This will create and run a <%=vars.product_name%> instance using the peer-to-peer topology and default configuration values. Another <%=vars.product_name%> instance on another system can be created and started in the same way.

     If you need to pin your tc Server instance to a specific tc Server runtime version, use the `--version` option when creating the instance.

 ## <a id="quick_start__section_4689A4FA609A4F4FB091F03E9BECA4DB" class="no-quick-link"></a>Additional Quick Start Instructions for Tomcat Module

 These steps provide a basic starting point for using the Tomcat module. For more configuration options, see [HTTP Session Management Module for Tomcat](session_mgmt_tomcat.html).

 1.  Modify Tomcat's `server.xml` and `context.xml` files. Configuration is slightly different depending on the topology you are setting up and the version of Tomcat you are using.

     For example, in a peer-to-peer configuration using Tomcat 9, you would add the following entry within the `<server>` element of server.xml:

     ``` pre
     <Listener className="org.apache.geode.modules.session.catalina.
                              PeerToPeerCacheLifecycleListener"
                              locator="localhost[10334]" />
     ```

     and the following entry within the `<context>` tag in the context.xml file:

     ``` pre
     <Manager className="org.apache.geode.modules.session.catalina.
                              Tomcat9DeltaSessionManager"/>
     ```

     See [Setting Up the HTTP Module for Tomcat](tomcat_setting_up_the_module.html) for additional instructions.

 2.  Restart the application server.

 ## <a id="quick_start__section_1587C3E55F06406EBD4AB13014A406D4" class="no-quick-link"></a>Additional Instructions for AppServers Module

 These steps provide a basic starting point for using the AppServers module with WebLogic, WebSphere or JBoss. For more configuration options, see [HTTP Session Management Module for AppServers](session_mgmt_weblogic.html).

 **Note:**

 -   The `modify_war` script relies upon a GEODE environment variable. Set the GEODE environment variable to the <%=vars.product_name%> product directory; this is the parent directory of `bin`.
 -   The `modify_war` script, described below, relies on files within the distribution tree and should not be run outside of a complete distribution.
 -   The `modify_war` script is a `bash` script and does not run on Windows.

 To set up the AppServers module, perform the following steps:

 1.  Run the `modify_war` script against an existing `.war` or `.ear` file to integrate the necessary components. The example below will create a configuration suitable for a peer-to-peer <%=vars.product_name%> system, placing the necessary libraries into `WEB-INF/lib` for wars and `lib` for ears and modifying any `web.xml` files:

     ``` pre
     $ bin/modify_war -w my-app.war -p gemfire.property.locators=localhost[10334] \
                       -t peer-to-peer
     ```

 2.  A new war file will be created called `session-my-app.war`. This file can now be deployed to the server.
	---
	title: HTTP Session Management Quick Start
	---

	<!--
	Licensed to the Apache Software Foundation (ASF) under one or more
	contributor license agreements. See the NOTICE file distributed with
	this work for additional information regarding copyright ownership.
	The ASF 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.
	-->

	In this section you download, install, and set up the HTTP Session Management modules.

	## <a id="quick_start__section_6A4A00B6DA404E10A5C29E5E31101445" class="no-quick-link"></a>Quick Start Instructions

	1. Download and install one of the application servers.

	\| Supported Application Server \| Version \| Download Location \|
	\|------------------------------\|-----------------------------\|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------\|
	\| tc Server \| 3.2 \| [https://network.pivotal.io/products/pivotal-tcserver](https://network.pivotal.io/products/pivotal-tcserver) \|
	\| Tomcat \| 8.5 \| [http://tomcat.apache.org/download-80.cgi](http://tomcat.apache.org/download-80.cgi) \|
	\| Tomcat \| 9.0 \| [https://tomcat.apache.org/download-90.cgi](https://tomcat.apache.org/download-90.cgi) \|

	The generic HTTP Session Management Module for AppServers is implemented as a servlet filter and should work on any application server platform that supports the Java Servlet 3.1 specification.

	2. The HTTP Session Management Modules installation .zip files are located in the `tools/Modules` directory of the product installation directory. Locate the .zip file for the HTTP Session Management Module that you wish to install. Unzip the appropriate HTTP Session Management Module into the specified directory for your application server:

	\| Supported Application Server \| Version \| Module \| Target Location for Module \|
	\|------------------------------\|-----------------------------\|----------------------------------------------------------\|----------------------------------------------------------------------------------\|
	\| tc Server \| 3.2 \| HTTP Session Management Module for Pivotal tc Server \| `<tc Server root dir>/templates` \|
	\| Tomcat \| 8.5 \| HTTP Session Management Module for Tomcat \| `$CATALINA_HOME` \|
	\| Tomcat \| 9.0 \| HTTP Session Management Module for Tomcat \| `$CATALINA_HOME` \|

	3. Complete the appropriate set up instructions for your application server described in the following sections:
	- [Additional Quick Start Instructions for tc Server Module](quick_start.html#quick_start__section_EE60463F524A46B7B83CE74C1C3E8E0E)
	- [Additional Quick Start Instructions for Tomcat Module](quick_start.html#quick_start__section_4689A4FA609A4F4FB091F03E9BECA4DB)
	- [Additional Instructions for AppServers Module](quick_start.html#quick_start__section_1587C3E55F06406EBD4AB13014A406D4)

	## <a id="quick_start__section_EE60463F524A46B7B83CE74C1C3E8E0E" class="no-quick-link"></a>Additional Quick Start Instructions for tc Server Module

	These steps provide a basic starting point for using the tc Server module. For more configuration options, see [HTTP Session Management Module for Pivotal tc Server](session_mgmt_tcserver.html). As a prerequisite, module set up requires a JAVA\_HOME environment variable set to the java installation.

	1. Navigate to the root directory of tc Server.
	2. Create a <%=vars.product_name%> instance using one of the provided templates and start the instance after starting up a locator. For example:

	``` pre
	$ gfsh start locator --name=locator1
	$ ./tcruntime-instance.sh create my_instance_name --template geode-p2p
	$ ./tcruntime-ctl.sh my_instance_name start
	```

	This will create and run a <%=vars.product_name%> instance using the peer-to-peer topology and default configuration values. Another <%=vars.product_name%> instance on another system can be created and started in the same way.

	If you need to pin your tc Server instance to a specific tc Server runtime version, use the `--version` option when creating the instance.

	## <a id="quick_start__section_4689A4FA609A4F4FB091F03E9BECA4DB" class="no-quick-link"></a>Additional Quick Start Instructions for Tomcat Module

	These steps provide a basic starting point for using the Tomcat module. For more configuration options, see [HTTP Session Management Module for Tomcat](session_mgmt_tomcat.html).

	1. Modify Tomcat's `server.xml` and `context.xml` files. Configuration is slightly different depending on the topology you are setting up and the version of Tomcat you are using.

	For example, in a peer-to-peer configuration using Tomcat 9, you would add the following entry within the `<server>` element of server.xml:

	``` pre
	<Listener className="org.apache.geode.modules.session.catalina.
	PeerToPeerCacheLifecycleListener"
	locator="localhost[10334]" />
	```

	and the following entry within the `<context>` tag in the context.xml file:

	``` pre
	<Manager className="org.apache.geode.modules.session.catalina.
	Tomcat9DeltaSessionManager"/>
	```

	See [Setting Up the HTTP Module for Tomcat](tomcat_setting_up_the_module.html) for additional instructions.

	2. Restart the application server.

	## <a id="quick_start__section_1587C3E55F06406EBD4AB13014A406D4" class="no-quick-link"></a>Additional Instructions for AppServers Module

	These steps provide a basic starting point for using the AppServers module with WebLogic, WebSphere or JBoss. For more configuration options, see [HTTP Session Management Module for AppServers](session_mgmt_weblogic.html).

	Note:

	- The `modify_war` script relies upon a GEODE environment variable. Set the GEODE environment variable to the <%=vars.product_name%> product directory; this is the parent directory of `bin`.
	- The `modify_war` script, described below, relies on files within the distribution tree and should not be run outside of a complete distribution.
	- The `modify_war` script is a `bash` script and does not run on Windows.

	To set up the AppServers module, perform the following steps:

	1. Run the `modify_war` script against an existing `.war` or `.ear` file to integrate the necessary components. The example below will create a configuration suitable for a peer-to-peer <%=vars.product_name%> system, placing the necessary libraries into `WEB-INF/lib` for wars and `lib` for ears and modifying any `web.xml` files:

	``` pre
	$ bin/modify_war -w my-app.war -p gemfire.property.locators=localhost[10334] \
	-t peer-to-peer
	```

	2. A new war file will be created called `session-my-app.war`. This file can now be deployed to the server.