Spencer Uresk

1. Tomcat Spencer Uresk

2. 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

3. 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

4. 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/

5. 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)

6. Tomcat Configuration Files • catalina.properties • server.xml • logging.properties • web.xml

7. 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?

8. 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)

9. 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

10. 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

11. 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}” />

12. 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

13. 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

14. 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)

15. 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

16. 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

17. 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.

18. 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

19. 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

20. 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

21. 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

22. 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/bCtxOior5sHlCR9Liwe K1aVsXw799yo4F6G4aowIDAQAB =====================Tomcat Public Key End=================== • This is used to encrypt values with the Encryption tool

23. 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.DecryptingStandardServer“ (add to server in server.xml) • Customization we made to decrypt any JNDI values that start with {encrypted}

24. 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

25. 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.html?module=tomcat/tomcat-crypto.html

26. Tomcat Encryption Tool • http://code.lds.org/maven-sites/stack/module.html?module=tomcat-encrypt-tool • Webstartapplication for encrypting values • Paste in the key • And the value you want encrypted • Use the encrypted value in your *.catalina.properties (or server.xml)

27. 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

28. 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

29. 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

30. 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

31. 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.html?module=tcat-deploy

32. 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

33. 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_Tomcat_Servers