The Global Configuration Plugin (or: Division not defined)

I recently installed the minicms demo on a virtual server (VPS) with 256 MB of RAM. While the good news is that it all went rather well given the memory constraints (there are even 80-100 MB of RAM remaining after booting minicms and the backend), I got caught on an unexpected front: if you access the server using a domain name (as in http://my.domain.net:8080), you get a “Division not defined” message when accessing the /war or /flexive-backend-war context. The quick solution (which wasn’t apparent to me, until I remembered the cause): use the IP address instead. What’s the problem, and how do we solve it?

[fleXive] has the concept of divisions. A single [fleXive] instance can serve multiple “divisions”, which are fully independent from each other and use separated databases (possibly on different hosts and from different vendors). The division of a web request is determined by looking at the URL: each division has a regular expression to match the URL pattern, the first division that matches the request pattern will be used to serve the request.

Now, this is less interesting for our small demo project, but very important for ASP-like deployments where you serve multiple customers using a single server. The major gotcha is that by default, the first (default) division matches only requests that use localhost or an IP address as the hostname. Any other request will lead to the “Division not defined” error, because the request URL does not match the pattern of the first (and only) division.

So how do we redefine the URL pattern of the first division? [fleXive] provides a web-based UI for the division mapping table through the global configuration plugin. Unluckily for us, this plugin does not get packaged by our default Maven project (mainly for  security reasons, because it uses a default login and this can of course wreak havoc with a running [fleXive] server).

First, since we use the Maven Jetty plugin, we have to deploy the plugin to Jetty. Open minicms/war/pom.xml and add the following dependency to the Jetty configuration:

<plugin>
   <groupId>org.mortbay.jetty</groupId>
   ...
   <dependencies>
      ...
      <dependency>
         <groupId>com.flexive</groupId>
         <artifactId>flexive-plugin-globalconfig</artifactId>
         <version>${flexive.version}</version>
      </dependency>
      ...
   </dependencies>
</plugin>

Restart Jetty, and open (using the IP address of your host) the URI /flexive-backend-war/globalconfig/index.xhtml. You should see a screen similar to this one:

Login using the default credentials of the global configuration. You get to the division configuration table, which lists for every division the pattern to be used for match request URLs and the assigned datasources (that must be defined in the application server).

Here we can see that the first division (the one that uses our H2 database) matches the following regular expression: (\d+\.\d+\.\d+\.\d+|localhost). Thus it will match either an IP address in the form of x.x.x.x (the first part) or the hostname localhost (the second part). To specify a “catch-all” pattern for the first division, click the “Edit” button of the row.

In the first column, enter “.*” (without the quotation marks!) as our new mapping. Click “Save changes”. The settings are not applied immediately, so we can still use the input box below the table for checking our pattern. Enter the desired URLs in “Find division for URL”, and verify that the first division is returned as a result. Finally, click “Store divisions in database” to have the settings applied to the running installation. You can then access the [fleXive] application using any hostname, and of course you could also add more divisions to serve other websites.

Of course the entire situation is somewhat unsatisfying, as it is very difficult for you as a fleXive user to figure out what’s going on. I think we need to address this issue in several ways:

• Improve the documentation of the global configuration plugin. While it’s pretty easy to understand once you get there, it’s not apparent that the global configuration plugin even exists.
• Perhaps use “.*” as the default mapping. If you want to use multiple divisions, you have to edit the division table anyway, and you’d use your own, hostname- or path-based naming scheme.
• Add a (disabled) dependency for the global configuration plugin to the Maven archetype (already did this, but this affects only new projects). The Ant-based distribution by default already packages the plugin for your own projects.
• Possibly figure out a way to configure the divisions without a web frontend. The problem I faced was that I couldn’t (and didn’t want to) launch Firefox on the virtual server (to be able to use localhost access), but I also couldn’t access the global configuration from the outside (you need a valid division to access the global configuration) – at least until I figured out that the IP would work. And by using an embedded, file-based H2 database, there’s no database server to connect to and modify the mappings manually.

Tutorial application stands alone

I reworked parts of the tutorials section of our reference documentation.  The tutorials are now offered as stand-alone source downloads that can be compiled with a current fleXive distribution. The chapter on the hello-world application also explains how to build this application “from scratch”. It should be possible to complete the application just by copy-and-pasting the source listings and following the instructions.

The previous version focused on explaining the source code itself, but it assumed that you’d only want to compile the example inside the main fleXive source tree (this still works, of course, it’s just not very useful for anybody developing a new application). You may also want to check out the chapter on Writing [fleXive] applications, which also explains how to use Maven for your own projects.