# salt.states.tomcat

## Manage Apache Tomcat web applications

Note

This state requires the Tomcat Manager webapp to be installed and running.

The following grains/pillars must be set for communication with Tomcat Manager to work:

    tomcat-manager:
        user: 'tomcat-manager'
        passwd: 'Passw0rd'

### Configuring Tomcat Manager

To manage webapps via the Tomcat Manager, you'll need to configure a valid user in the file `conf/tomcat-users.xml`.

conf/tomcat-users.xml

     <?xml version='1.0' encoding='utf-8'?>
     <tomcat-users>
         <role rolename="manager-script"/>
         <user username="tomcat-manager" password="Passw0rd" roles="manager-script"/>
     </tomcat-users>

Notes

- Using multiple versions (aka. parallel deployments) on the same context path is not supported.

- More information about the Tomcat Manager: http://tomcat.apache.org/tomcat-7.0-doc/manager-howto.html

- If you use only this module for deployments you might want to restrict access to the manager so it's only accessible via localhost. For more info: http://tomcat.apache.org/tomcat-7.0-doc/manager-howto.html#Configuring_Manager_Application_Access

- Last tested on:
    Tomcat Version:

      Apache Tomcat/7.0.54

    JVM Vendor:

      Oracle Corporation

    JVM Version:

      1.8.0_101-b13

    OS Architecture:

      amd64

    OS Name:

      Linux

    OS Version:

      3.10.0-327.22.2.el7.x86_64

salt.states.tomcat.mod_watch(name, url='http://localhost:8080/manager', timeout=180)

  The tomcat watcher, called to invoke the watch command. When called, it will reload the webapp in question

  Note

  This state exists to support special handling of the `watch` requisite. It should not be called directly.

  Parameters for this function should be set by the state being triggered.

salt.states.tomcat.undeployed(name, url='http://localhost:8080/manager', timeout=180)

  Enforce that the WAR will be undeployed from the server

  name

    The context path to undeploy.

  urlhttp://localhost:8080/manager

    The URL of the server with the Tomcat Manager webapp.

  timeout180

    Timeout for HTTP request to the Tomcat Manager.

  Example:

      jenkins:
        tomcat.undeployed:
          - name: /ran
          - require:
            - service: application-service

salt.states.tomcat.wait(name, url='http://localhost:8080/manager', timeout=180)

  Wait for the Tomcat Manager to load.

  Notice that if tomcat is not running we won't wait for it start and the state will fail. This state can be required in the tomcat.war_deployed state to make sure tomcat is running and that the manager is running as well and ready for deployment.

  urlhttp://localhost:8080/manager

    The URL of the server with the Tomcat Manager webapp.

  timeout180

    Timeout for HTTP request to the Tomcat Manager.

  Example:

      tomcat-service:
        service.running:
          - name: tomcat
          - enable: True

      wait-for-tomcatmanager:
        tomcat.wait:
          - timeout: 300
          - require:
            - service: tomcat-service

      jenkins:
        tomcat.war_deployed:
          - name: /ran
          - war: salt://jenkins-1.2.4.war
          - require:
            - tomcat: wait-for-tomcatmanager

salt.states.tomcat.war_deployed(name, war, force=False, url='http://localhost:8080/manager', timeout=180, temp_war_location=None, version=True)

  Enforce that the WAR will be deployed and started in the context path, while making use of WAR versions in the filename.

  Note

  For more info about Tomcats file paths and context naming, please see http://tomcat.apache.org/tomcat-7.0-doc/config/context.html#Naming

  name

    The context path to deploy (incl. forward slash) the WAR to.

  war

    Absolute path to WAR file (should be accessible by the user running Tomcat) or a path supported by the `salt.modules.cp.get_url` function.

  forceFalse

    Force deployment even if the version strings are the same. Disabled by default.

  urlhttp://localhost:8080/manager

    The URL of the Tomcat Web Application Manager.

  timeout180

    Timeout for HTTP requests to the Tomcat Manager.

  temp_war_locationNone

    Use another location to temporarily copy the WAR file to. By default the system's temp directory is used.

  version''

    Specify the WAR version. If this argument is provided, it overrides the version encoded in the WAR file name, if one is present.

    New in version 2015.8.6.

    Use `False` or blank value to prevent guessing the version and keeping it blank.

    New in version 2016.11.0.

  Example:

      jenkins:
        tomcat.war_deployed:
          - name: /salt-powered-jenkins
          - war: salt://jenkins-1.2.4.war
          - require:
            - service: application-service

  Note

  Be aware that in the above example the WAR `jenkins-1.2.4.war` will be deployed to the context path `salt-powered-jenkins##1.2.4`. To avoid this either specify a version yourself, or set version to `False`.