ModjyDeployment » History » Version 9
Alan Kennedy, 2016-08-27 02:33 PM
Fixed more broken links
h1. Deploying modjy web applications
h2. Choosing a J2EE container
In order to run modjy, you will need to have a J2EE-compliant servlet container. There are dozens of such competing containers on the market, both commercial and non-commercial, both open-source and closed-source. You can find a current and comprehensive list of them here: "Wikipedia: List of servlet containers":http://en.wikipedia.org/wiki/List_of_Servlet_containers.
If you are already using a particular servlet container, then you've probably chosen it for good reasons, and are unlikely to change it. Since modjy was written to the J2EE standard, you should be able to run modjy without modification, and the below documentation should be sufficient to help you configure it. But you will need to know the in-and-outs of how to configure your container for modjy: I'm not going to include installation instructions for every container here.
If you are picking a servlet container for the sole purpose of running modjy, then I recommend that you use "Apache Tomcat":http://tomcat.apache.org/, for the following reasons
# Because all of the modjy documentation examples relate to it
# Because it is one of the simplest containers to get up and running
# Because it is one of the most stable, most configurable, well supported and well documented containers there is.
So if you don't yet have a running J2EE servlet container, I recommend that you "download the latest version of Tomcat":http://tomcat.apache.org/, install it and get it running now, before proceeding.
h2. The steps required to install and configure modjy web applications
From here, I will assume that you already have a J2EE container up and running. You should be satisfied that your container is fully operational, i.e. by using some container-specific test mechanism, before attempting to install modjy.
You should also have "jython":http://www.jython.org/downloads.html installed and operational on your target system.
The following are the steps that you will need to follow, in order: each is explained in detail below.
# [[ModjyDeployment#install_webapp|Install the modjy demo web application]], including it's *web.xml* configuration file.
# [[ModjyDeployment#jython_jar|Place the jython.jar file]]
# [[ModjyDeployment#configuring_modjy|Set the values of modjy configuration parameters]]
# [[ModjyDeployment#testing_modjy|Test that modjy is running]]
# [[ModjyDeployment#serving_all|Optionally configure modjy to service all requests to the container]](not just requests for a subset of the URI space).
h2. Installing the modjy servlet
It should be easy to install modjy as a web application. Simply take a copy of the *modjy_webapp* directory in the *Demo* subdirectory of the jython distribution, and drop it in the location where your container expects to find web applications.
The default installation of Apache Tomcat has a subdirectory called *webapps*. If you're running Tomcat, simply drop the *modjy_webapp* directory in there, (maybe) restart your container, and you should be up-and-running.
If you're using a different J2EE container, or a non-default installation of Tomcat, you'll need to read your container documentation to find out where web applications should live.
The *modjy_webapp* directory contains the following files and directories
|<.WEB-INF|This standard J2EE directory contains the support resources required for a web application.|
|<.WEB-INF/web.xml|This file contains configuration for this instance of the modjy servlet. The J2EE servlet <init-param> parameters are used to control the operation of modjy. Setting configuration parameters is described below. The configuration parameters which can be set are described in a separate document: [[ModjyConfiguration|modjy configuration]].|
|<.WEB-INF/lib|This is the standard J2EE directory where servlet support jars, etc, should be placed. In the simple case, this is where the jython.jar file should go. See below under [[ModjyDeployment#jython_jar|Placing the jython.jar file]] for more details.|
|<.WEB-INF/lib-python|This directory is treated specially by modjy. Firstly, lib-python is added to sys.path, which means that any python libraries you wish to use can be dropped in here, and they will automatically become available to your code. Secondly, the directory is searched for "python .pth files":https://docs.python.org/2/library/site.html#module-site . These files are simple text files, each line of which is added directly to sys.path. So if you want to use .jar files, .zip files or .egg files containing python code, you should create a text file, whose name ends with *.pth*, listing each of those files, one per line, and place the file in the lib-python directory. All files in the lib-python directory whose names end with *.pth* are scanned.|
h2. Placing the jython.jar file
The java .class file for the the modjy servlet (com.xhaus.modjy.ModjyJServlet.class) is contained in the *jython.jar* file, so you must place the jython.jar file in the servlet container hierarchy so that it is available when the modjy servlet class is being loaded.
Standard J2EE classloading behaviour when looking for support resources is to look first inside the *WEB-INF/lib* directory for a web application. So if you're just running a single instance of the modjy servlet, you can place the jython.jar file in there, and read no further in this section.
If you're running more than one instance of the servlet, you have a choice of what to do.
# Place multiple copies of jython.jar, one in the *WEB-INF/lib* directory of each instance.
# Place a single copy of jython.jar in a place where all instances of the modjy web applications can find it. Picking the right place requires knowing how the classloader hierarchy of your container works, so you may need to do some reading. On the standard Tomcat installation, there is a directory called *lib*, which is shared between all web applications, so you could put it there. More information available in the "Tomcat documentation on classloading":http://tomcat.apache.org/tomcat-8.0-doc/class-loader-howto.html
If you neglect to make jython.jar available to the modjy servlet, or put it in the wrong place, then you will get messages like this in your error log: *java.lang.NoClassDefFoundError: com/xhaus/modjy/ModjyJServlet*.
h2. Configuring modjy
Configuring modjy is done inside the *<servlet>* elements in web.xml files. You have to define a name for the servlet, and the name of the class that implements it. So the beginning of your servlet declaration for modjy will look something like this
<!-- Parameters omitted -->
After this is a series of *initialization parameters*, given as name/value pairs. These parameters control the operation of modjy, for example logging, caching, threading, etc, behaviour. All of those parameters, what they mean, and their permitted and default values, are described in a separate document: the [[ModjyConfiguration|modjy configuration reference]].
There is only a single parameter that is always required: the *python.home* property, which gives the home directory of the local jython installation. Without knowing this value, modjy cannot operate, so this is the first thing you should check if things aren't working.
Specifying python.home permits jython to locate its registry file, its cache of pre-compiled packages, etc, etc. For more information on the effects of setting python.home, see the "The Jython Registry":http://www.jython.org/jythonbook/en/1.0/appendixA.html documentation.
There is one final web.xml configuration value which needs to be specified: the *servlet-mapping*. This maps an URL pattern to the servlet declared above. Inside the web.xml file, you will need a fragment like this
h2. Testing that modjy is running.
First off, be sure that your container is running. Assuming that you're using the out-of-the-box configuration, and that you're running your container on port 8080 on localhost, then resolving the following URL should render proof that modjy is indeed running.
The returned page should show some version details for jython, and the JVM version in which it is running. It will also display a table showing the contents of the WSGI environment, as seen by all WSGI applications running under modjy.
h2. Deployment with WAR files.
WAR files are a single file archive format which allows you to package all of the support files for a java we application into a single archive. Generating a WAR file is described on the page [[ModjyWarPackaging|modjy WAR packaging]].
h2. Serving all requests to a container with modjy.
h3. Changing the uri space served by modjy
If you successfully installed the modjy servlet according to the instructions above, using the suggested name *modjy_webapp*, then you will find that modjy will be used by the container to service all requests which look like this: */modjy_webapp/**. However, you probably don't want to use URIs like that.
If you want modjy to serve requests for a different uri subset, simply rename the web application directory to something else: e.g. *my_app_uri*, in which case your uris will look like */my_app_uri/*, etc.
h3. Serving an entire uri space with modjy
You can also use modjy to serve all URIs in a container: See [[ModjyEntireUriSpace|Serving an entire URI space with modjy]] for details.