Virtual Hosting Guide

Introduction

Virtual hosting is a well established practice of mapping more than one domain name to a single host platform. Since the NetKernel module system provides encapsulated URI address spaces, creating virtual hosts is quite straightforward.

To use this guide you should first have read the Module Guide.

Transport Requests

Virtual hosting requires that the transports you are using in your application provide you with the hostname in the URI of request they are making. The URI specification states that a server host name is the first item after the URI scheme declaration, as follows

scheme://host:port/path/resource

The jetty HTTP transport always provides the host in it's requests to the Kernel. For example, a request to Jetty from a web-browser on the same host as the NetKernel installation might be

jetty://localhost:1060/a/path/to/a/resource

A Module is a Virtual Host

Since virtual hosting is really just URI encapsulation, a module is already a generalization of a virtual host.

Implementing a Virtual Host Configuration

Implementing a virtual host configuration is very simple.

1. Create a Fulcrum module that hosts a transport which issues requests with a hostname part.
2. Import any number of secondary modulesinto the Fulcrum. Each secondary module should export a public URI address space that matches a different host.
3. Do nothing in the Fulcrum. Allow NetKernel's ModuleManager to issue the request to the matching secondary module.

Depending on how you implement your secondary virtual host module you may wish to use a URI rewrite rule to map the external request down to the root of the module's internal address space. Here's a rule which does that

Multiple XAR Directories

If you want to keep things tidy you can make a new XAR directory for each set of modules that make up the virtual host application. These can be specified in the system.xml NetKernel configuration document.