Project

General

Profile

ModjyDeployment » History » Version 8

Alan Kennedy, 2016-08-27 02:28 PM
Fixed a broken link to the registry documentation

1 1 Alan Kennedy
h1. Deploying modjy web applications
2
3 2 Alan Kennedy
{{toc}}
4
5 6 Alan Kennedy
h2. Choosing a J2EE container
6 1 Alan Kennedy
7
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.
8
9
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.
10
11 7 Alan Kennedy
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
12 1 Alan Kennedy
13
 # Because all of the modjy documentation examples relate to it
14
 # Because it is one of the simplest containers to get up and running
15
 # Because it is one of the most stable, most configurable, well supported and well documented containers there is.
16
17 7 Alan Kennedy
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.
18 1 Alan Kennedy
19 6 Alan Kennedy
h2. The steps required to install and configure modjy web applications
20 1 Alan Kennedy
21
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.
22
23
You should also have "jython":http://www.jython.org/Project/download.html installed and operational on your target system.
24
25
The following are the steps that you will need to follow, in order: each is explained in detail below.
26
27 3 Alan Kennedy
 # [[ModjyDeployment#install_webapp|Install the modjy demo web application]], including it's *web.xml* configuration file.
28
 # [[ModjyDeployment#jython_jar|Place the jython.jar file]]
29
 # [[ModjyDeployment#configuring_modjy|Set the values of modjy configuration parameters]]
30
 # [[ModjyDeployment#testing_modjy|Test that modjy is running]]
31
 # [[ModjyDeployment#serving_all|Optionally configure modjy to service all requests to the container]](not just requests for a subset of the URI space).
32 1 Alan Kennedy
33 6 Alan Kennedy
h2. Installing the modjy servlet
34 1 Alan Kennedy
35
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.
36
37 7 Alan Kennedy
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.
38 1 Alan Kennedy
39
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.
40
41
The *modjy_webapp* directory contains the following files and directories
42
43
44
|Path|Description|
45
|<.WEB-INF|This standard J2EE directory contains the support resources required for a web application.|
46
|<.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]].|
47 4 Alan Kennedy
|<.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.|
48 1 Alan Kennedy
|<.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":http://docs.python.org/inst/search-path.html#search-path. 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.|
49
50 6 Alan Kennedy
h2. Placing the jython.jar file
51 1 Alan Kennedy
52
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.
53
54
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.
55
56
If you're running more than one instance of the servlet, you have a choice of what to do.
57
58
 # Place multiple copies of jython.jar, one in the *WEB-INF/lib* directory of each instance.
59 7 Alan Kennedy
 # 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
60 1 Alan Kennedy
61
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*.
62
63 6 Alan Kennedy
h2. Configuring modjy
64 1 Alan Kennedy
65
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
66
67
<pre><code>
68
<servlet>
69
    <servlet-name>modjy</servlet-name>
70
    <servlet-class>com.xhaus.modjy.ModjyJServlet</servlet-class>
71
    <!-- Parameters omitted -->
72
    <load-on-startup>1</load-on-startup>
73
</servlet></code>
74
</pre>
75
76
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]].
77
78
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.
79
80 8 Alan Kennedy
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.
81 1 Alan Kennedy
82
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
83
84
<pre><code>
85
<servlet-mapping>
86
    <servlet-name>modjy</servlet-name>
87
    <url-pattern>/*</url-pattern>
88
</servlet-mapping></code>
89
</pre>
90
91 6 Alan Kennedy
h2. Testing that modjy is running.
92 1 Alan Kennedy
93
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.
94
95
<pre>
96
http://localhost:8080/modjy_webapp/
97
</pre>
98
99
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.
100
101 6 Alan Kennedy
h2. Deployment with WAR files.
102 5 Alan Kennedy
103
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]].
104
105 6 Alan Kennedy
h2. Serving all requests to a container with modjy.
106 1 Alan Kennedy
107
h3. Changing the uri space served by modjy
108
109
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.
110
111
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.
112
113
h3. Serving an entire uri space with modjy
114
115
You can also use modjy to serve all URIs in a container: See [[ModjyEntireUriSpace|Serving an entire URI space with modjy]] for details.