Servlex can be installed either using a graphical installer, or by deploying the standalone WAR file in the servlet container of your choice. The former approach is indeed the easiest one, whilst the latter is the most flexible.
This method requires you to download a file, execute it, choose the directory where to install Servlex, and that is pretty much it! It comes with Tomcat pre-bundeled, so you do not have to worry about scarry details. The only pre-requisite is to have Java installed, with JAVA_HOME properly set. Please follow those instructions if you do not have Java yet (choose the latest JDK for your platform).
Download the latest installer from the download area, and execute
it. You can simply double-click on it, or from the command-line just execute:
java -jar servlex-n.n.n-installer.jar. Follow the instructions, that's it!
If you have a graphical interface (like on most desktops and laptops), it will
use friendly dialog boxes, and if you do not (like on most distant servers) it
will use a textual interface.
At this point, you might want to have a look at the available
configuration options before starting Servlex, for instance if you
want to change the port Servlex listen to (by default it is
start Servlex, just execute
Windows) and go to http://localhost:19757/manager/.
Now you can have a look at the User Guide.
If you want to install Servlex into the servlet container of your choice, download the latest ZIP file from the download area. It contains a suitable WAR file and installation instructions. Once installed in your servlet container, you might want to have a look at the available configuration options as well.
If you install the WAR file, you will have to set up the repository for web applications. You will have to install the webapp manager as well, if you need it (by using the REST API or the command line tools). For reference, here is what the build process exactly does with the WAR file to bundle it with Tomcat, in order to create the installer:
- setup Tomcat class loader to support extension package JARs from the repo
- create the file
[tomcat]/repo/.expath-web/webapps.xml, with the content detailed below
- install latest
- install latest
expath-http-client-saxon-n.n.n.xaw(the manager depends on it)
- install latest
expath-zip-saxon-n.n.n.xaw(the manager depends on it)
- add some properties to
Deploy the WAR
There are a lot of different Java EE Servlet containers out there. Each has its own ways to deploy a WAR file, and to be configured. This documentation describes how to install Servlex on Tomcat. If you use another one, you will have to adapt the steps. If you do, please share your experience on the EXPath mailing list.
The ZIP release file contains the WAR file to deploy (as well as the simple JAR
file, would you ever need it.) It contains also the JAR file providing the
repo-aware class loader for Tomcat, called
servlex-loader. This class loader
is necessary because extensions for Saxon and Calabash can be installed as XAR
files, in the package repository. It is specific to Tomcat. To install it:
- copy the JAR file to
[tomcat]/lib/(it must be Tomcat's own lib/ directory)
- create the file
[tomcat]/conf/catalina/localhost/servlex.xml, with the following content:
<Context path='/servlex'> <Loader loaderClass="net.servlex.loader.RepoClassLoader"/> </Context>
The ZIP release file also contains two scripts:
are convenience shell scripts to launch the command-line versions of resp. the
EXPath Repository Manager and Saxon. They are setup to work from within
[tomcat]/bin/. If you put them some place else, they are well documented, and
you should be able to adapt the few paths to accomodate your own configuration.
Setup the repo
You need an EXPath package repository in order to install the webapps managed by
Servlex. This is a regular repository, augmented with a private directory
dedicated to web applications:
.expath-web/. Just create the repo directory,
and create the file
.expath-web/webapps.xml within it, with the following
<webapps xmlns="http://expath.org/ns/webapp"> <!-- Contains elements like: <webapp root="myapp" enabled="true"> <package name="http://example.org/my/webapp"/> </webapp> --> <webapp root="manager"> <package name="http://servlex.net/app/manager"/> </webapp> </webapps>
Then install the three following webapps (the Webapp Manager and both its dependencies):
In order to do so, you can use the REST deploy endpoint of Servlex. See the User Guide for comprehensive documentation, but you can use the following commands and adapt them as needed (I use HTTPie myself, but you can use CURL as well, as detailed in the User Guide):
http POST :19757/servlex/~rest/deploy/manager @webapp-manager-n.n.n.xaw http POST :19757/servlex/~rest/deploy @expath-http-client-saxon-n.n.n.xaw http POST :19757/servlex/~rest/deploy @expath-zip-saxon-n.n.n.xaw
Of course, if you do not want to use the web interface Webapp Manager, and install packages only through the REST endpoint, you do not have to install the manager (and none of its dependencies.)
The properties added to the Tomcat configuration file are as following. Most of them are commented out, but they serve as a reference for what properties exist.
That (should be) it!
You can now access the Webapp Manager at (depending on the port number Servlex runs on): http://localhost:8080/servlex/manager/.
The following step is to have a look at the User Guide.