TomcatSpencer Uresk

Notes

• This is a training NOT a presentation• Please ask questions• This is being recorded• https://tech.lds.org/wiki/Java_Stack_Training• Prerequisites– Basic Java– Installed LDSTech IDE (or other equivalent)– Servlet training highly recommended

Objectives

• By the end of this training, you should be able to:• Add a JNDI property• Change a JNDI property for a specific environment• Get your project properly deployed locally and be able to

switch environments• Deploy a project to a Tcat server• Encrypt a sensitive property value• Enable remote debugging in one of your environments

(time permitting)• Have some idea of where to look when troubleshooting

deployment-related problems

Tomcat Overview

• Servlet container originally built by Sun, then donated to the Apache Software Foundation

• Free, open-source• Lightweight, fast startup• Tomcat 6 is our currently supported version• Implements servlet 2.5, JSP 2.1• http://tomcat.apache.org/

Tomcat Directory Structure

• bin/ Contains scripts for starting and stopping Tomcat.

• conf/ Contains configuration files• lib/ Contains basic libraries Tomcat uses• logs/ Contains runtime logs• temp/ Contains temporary files (ie, uploaded files)• webapps/ Is where web applications are deployed to• work/ Contains files Tomcat temporarily creates (ie,

compiled JSPs)

Tomcat Configuration Files

• catalina.properties• server.xml• logging.properties• web.xml

Why is external configuration necessary?

• Can’t I just drop a WAR file into webapps/ and call it good?

• Configuration is required for most non-trivial apps

• You can embed that in the WAR, but what happens if it ever changes?

Deployment Configuration Philosophy

• Based on our experience and feedback from Stack 2.x projects

• One artifact for all lanes• Keep configuration in one place• Make it possible to change configuration without requiring a

redeployment• Use existing, well-known ways of specifying configuration

(JNDI properties)• Support encryption of properties• Consistency across environments (including local

development environment)

What is JNDI?

• Java Naming and Directory Interface• Allows Java clients to discover and lookup objects

via a name• Allows us to lookup configuration properties (ie,

database connection information) by name and have it be external to the application itself

Adding a JNDI Property (Example)

• Add entry to server.xml under GlobalNamingresources• <Environment name=“someProperty”

type=“java.lang.String” value=“foo” />• This creates the property

• Add mapping in context.xml• <ResourceLink name=“appProperty”

global=“someProperty” />• This maps it to a specific application

Defining JNDI Properties

• Value can now be consumed in Spring and injected into whatever beans need it:• <jee:jndi-lookup id=“jndiProperty” jndi-

name=“appProperty” />• We can abstract the value of the property by

putting it in catalina.properties• Add some.property=foo to catalina.properties• Change server.xml config to look like this:

<Environment name=“someProperty” type=“java.lang.String” value=“${some.property}” />

The Deploy Project

• All of this configuration is grouped into one project for you

• Every Stack 3 project has a deploy project (in /deploy)

• Packaging type of tomcat-deployable (results in a zip being created)

• Uses the Stack Tomcat Deployable plugin• This is where everything related to deployment

lives

What does it include?

• Any WAR files that are part of your project (referenced as dependencies in the deploy POM)

• Any libraries that need to be loaded by Tomcat for your project to work

• Configuration files• JVM arguments

Configuration Files

• Standard Tomcat configuration files that we saw a few slides ago

• Can be prefixed by an environment name (ie, dev.catalina.properties)

• Prefix determines which files is used• You specify the prefix at deploy time• If a property file with that prefix doesn’t exist,

the default is used (ie, catalina.properties)

JVM Args

• Are defined slightly differently• All JVM args are in one file – jvmargs.properties• Properties are prefixed by the environment• The suffix groups properties• The following properties define the same

property but for different environments:dev.jvmarg.memory= -Xmx512mprod.jvmarg.memory= -Xmx1024mjvmarg.memory= -Xmx128m

Tomcat Maven Plugin

• You could collect all these files yourself, create a ZIP and have a deployment package that works properly

• But, we’ve made it easier by creating a Maven plugin that gathers everything up into a ZIP file

• This can be unzipped and started, deployed via the Tcat Maven plugin (discussed later), or deployed via the Tcat Console plugin.

• http://code.lds.org/maven-sites/stack/module.html?module=tomcat-maven-plugin

Tomcat Maven Plugin, Goals

• Start• Starts a local Tomcat instance

• Stop• Stops a local Tomcat instance

• Deploy• Deploys a Tomcat instance in its own process. Can be

used to deploy an application remotely via SSH.• Distro• Creates a Tomcat instance for deployment of a

deployable.

Tomcat Plugin, Config goal

• Used for creating and configuring Tomcat instances using a deployable package

• Useful for creating a Tomcat instance when you aren’t using the LDSTech IDE

• Config goal does this by configuring a Tomcat instance without deploying your project to it

• You then point IntelliJ (or Netbeans, etc) to this Tomcat instance

LDSTech IDE Integration

• LDSTech IDE works well with the deployable plugin and WTP

• Automatically copies any config files out to the server managed by WTP

• You can set the environment you want to use in the Server properties page

Lab #1

• Create a project using Stack Starter• http://code.lds.org/maven-sites/stack/

• Get it working on a properly configured Tomcat server, either via the LDSTech IDE or by using the Deploy plugin to build an instance

• Add a JNDI property• Check to make sure it works locally• Make it so that the value is different in stage• Change your local configuration to use Stage to see

your changed variable

Tomcat Encryption

• Sometimes it is useful to be able to encrypt a sensitive property (ie, database password)

• Our Encryption solution consists of two pieces:• Tomcat Encryption Module for Tomcat• Tomcat Encryption Tool

• Uses a Public/Private key pair• Public key is used to encrypt• Private key is used to decrypt

Tomcat Encryption

• Public key is printed out to logs/console when the server starts up:

====================Tomcat Public Key Begin================== MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAgYU8qMl7vxAj36uYh cI5U7aynSH1ioMmAShsyARZEb47w5MHCofQ2HifWfgQfZjtXKfHxhWL0miBw4 BwQB0c/8JJgBkTZ31EjPO9tq1QKQMJeNEaKx1Kkl8qA3phPpqMn5RqcUie0LJ 5VLRhRizCZgMtb0j1ancfrM7SDKd0wU9bN+l/xqVJB7N3LS6YD3/3OzXheCEE 0S7gR+n5A0qheT0hjINpovWl5TeDTiZAQXDYFj9TRANtwNyBLWdWGKw6gyG3a mzwmgo+9yDXBQifnUiVIc8+GX+osUIn1j4xOTQr01/bCtxOior5sHlCR9LiweK1aVsXw799yo4F6G4aowIDAQAB=====================Tomcat Public Key End===================

• This is used to encrypt values with the Encryption tool

Tomcat Encryption Module

• Private key used to decrypt encrypted values in Tomcat

• Steps to use• Add stack-tomcat-module to your deploy project’s

pom.xml• className="org.lds.stack.tomcat.decrypt.Decrypting

StandardServer“ (add to server in server.xml)• Customization we made to decrypt any JNDI

values that start with {encrypted}

Tomcat Encryption Module

• Once it is setup, you can add encrypted values to catalina.properties (it also works in server.xml) and they’ll be decryped

• Values must start with {encrypted}• By default, it tries to load the KeyPair from $

{user.home}/.stack/tomcatCfg.key• If it isn’t there, it creates a KeyPair and stores it

there

Tomcat Encryption Module

• You can set a custom key location• Or use a KeyStore• Documentation can be found here:• http://code.lds.org/maven-sites/stack/module.ht

ml?module=tomcat/tomcat-crypto.html

Tomcat Encryption Tool

• http://code.lds.org/maven-sites/stack/module.html?module=tomcat-encrypt-tool

• Webstart application for encrypting values• Paste in the key• And the value you want encrypted

• Use the encrypted value in your *.catalina.properties (or server.xml)

Lab #2

• Encrypt the property we added in Lab #1• Put that value in your catalina.properties• Make sure your application can still read it

Tcat

• Tcat is a product from Mulesoft that ICS has purchased

• Adds management and monitoring capabilities to Tomcat

• Provides a REST API that we use to automate a lot of deployment-related tasks

• More information from Middleware:• http://middleware/tomcat

Tcat: Common tasks

• Login with your LDS Account info• You can see the status of any servers you have

access to• You can (depending on permissions) also restart

servers, view files, and view other information related to the server

• Log files are located under the Logs tab

Lab #3

• Login to my server• username: training, password: training• View the state of my servers• Download the catalina.out for the server that is

up• Familiarize yourself with the console

Tcat Deployment Maven Plugin

• Used to deploy deployment packages to Tcat servers

• Uses Tcat REST APIs to do this• Can be run as part of your build or from the

command line• http://code.lds.org/maven-sites/stack/module.ht

ml?module=tcat-deploy

Tcat Plugin, Common Terms

• We deploy to server groups – groups of servers that represent one application in one lane (ie, STACK_PETSTORE_DEV)

• Every deployment has to reference a console url – this is not the server you are deploying to, but the server that manages your server

• Username and password have to be specified for each deployment, and the user must have deployment rights for the group you specify

Remote Debugging Tomcat

• Remote debugging can be incredibly useful for tracking down bugs that you can’t reproduce locally

• You enable it by setting a JVM argument to turn it on

• dev.jvmarg.debug=-Xdebug -Xrunjdwp:transport=dt_socket,server=y,suspend=n,address=7007

• You can then connect to it using your IDE• https://tech.lds.org/wiki/Remote_Debugging_Tomc

at_Servers