Creating offline hosting package

In Zoo infrastructure the most convenient way to prepare the server to host some application is to install appropriate technology Hosting Package from Zoo –> Packages on it. These hosting packages include everything needed to run an application of particular type on a previously clean system. And all these packages can be installed offline using Web Platform Installer command line tool called WebpiCmd.exe. You can find official webpicmd.exe syntax reference here: http://www.iis.net/learn/install/web-platform-installer/web-platform-installer-v4-command-line-webpicmdexe-rtw-release

To install Hosting Package on a machine without Internet access you will first need to create an offline installation package. And you will first need a workstation that is connected to the Internet to do this. Let’s call it internet-enabled machine. So install Microsoft Web Platform Installer on the internet-enabled machine. Then run Windows Command Prompt as Administrator – right click on Start –> Accessories –> Command Prompt and select Run as administrator.

Running Command Prompt as administrator is needed to avoid need of opening new window on every WebpiCmd.exe command, so you can see the command output. If webpicmd.exe file is not in your Path, you can find it by navigating to

cd "C:\Program Files\Microsoft\Web Platform Installer"

Assume we need to install Redmine on the internet-disabled machine. This means we need to create offline installation for Ruby Hosting Package first. To install a product using WebpiCmd.exe you need to know it’s internal name. We can use /List mode to list all products and applications available with their internal names. It is better to save output into products.txt file because the list is long and may be truncated in the Command Prompt window. So run this command:

webpicmd.exe /List /ListOption:All /Feeds:http://www.helicontech.com/zoo/feed.xml > products.txt

Here is a list of all Hosting Packages with their internal names currently available for your convenience:

CFMLHostingPackage     CFML Hosting Package
JavaHostingPackage     Java Hosting Package
RubyHostingPackage     Ruby Hosting Package
NodejsHostingPackage   Node.js Hosting Package
PerlHostingPackage     Perl Hosting Package
PHPHostingPackage      PHP Hosting Package
PythonHostingPackage   Python Hosting Package

Please run the following command to create offline copy of Ruby Hosting Package product and all it’s possible dependencies:

WebpiCmd.exe /offline /Products:RubyHostingPackage /Path:C:\offline-package /Feeds:http://www.helicontech.com/zoo/feed.xml

This command will create a copy of al feeds, installation packages and other dependencies that may be required to install Ruby Hosting Package on another machine in the C:\offline-package folder. The /Products:RubyHostingPackage key is a comma separated list of products you are saving for offline usage. Notice C:\offline-package\bin folder – there you may find a copy of WebpiCmd.exe you will be using to install products on the internet-disabled system. Please copy content of the C:\offline-package folder to the internet-disabled machine, navigate to the C:\offline-package\bin folder and run following command to install products:

WebpiCmd.exe /install /Products:RubyHostingPackage /XML:C:\offline-package\feeds\latest\webproductlist.xml /Feeds:C:\offline-package\feeds\latest\supplementalfeeds\feed.xml /AcceptEula

This will install Ruby Hosting Package without internet access required.

Warning: Same technique will work for any other Hosting Package except Java Hosting Package. Because Oracle currently prohibit inclusion of JDK into any other packages or feeds we cannot include JDK directly into feed. You will need to download JDK 7 from Oracle web site separately and install it on internet-disabled machine. Once installed Helicon Zoo will recognize it’s installation and you can install Java Hosting Package then without internet access, all other components will be installed successfully.

Installing application

The hosting package is installed and server is ready to host the application. Please don’t try to create offline installation package of the application, such as Redmine or Python project template – this will not work because most of applications, like Redmine, will require internet access to install gems or some other components anyway. Instead of creating offline installation package for the application you will need to install needed application on the internet-enabled machine first. Please follow the instruction for specific application to install it. For example you can find detailed Redmine installation instruction here. Make sure to use Helicon Zoo Web Console or Helicon Zoo Manager Start IDE function to run console and IDE for applications so all components and dependencies (like gems, modules, etc.) will be installed in the application’s web site folder. Some technologies, like Java, will pack dependencies into the application folder by default. Some other needs additional means, like running web console, etc. While Helicon Zoo provides all needed tools to develop self-contained applications, it is up to developer to maintain application portability and pack all dependencies inside, which may require some sort of development discipline.

After you installed application on the internet-enabled machine make sure it is working as expected. If application needs additional configuration, configure it. Then, if you configured application following Helicon Zoo best practice, you can simply copy the application’s web site folder to another machine with required Hosting Package installed following normal deployment process and it will work. No internet access should be required for this operation again.

1. Helicon Zoo now include GUI manager, where you can configure various aspects of Zoo engine. You can edit existing engines, clone or add new engines, enable or disable engines, ets. Go to Start –> Helicon –> Zoo –> Helicon Zoo Manager to start it.

   

2. With Helicon Zoo Manager you can edit individual application settings, like engines used, environment variables, etc.

   

3. Now you can control which engines are allowed to use for individual web sites. This is useful for hosting services were administrators wish to restrict user abilities to call particular engines, even if corresponding software is installed in the system.

   

4. The most important feature is built-in web console – an HTML based command line application where users can run console commands directly to the web applications. This feature is required for most Ruby, Python, Node.js and Perl projects as well for some other web application technologies that rely on console commands. This web console is launched in the web application context and configured to use local application path, therefore all commands users call in this console will apply to the application folder. For example ‘gem install’ Ruby command will allow users to download and install gems into the web site’s local folder where they will run with Helicon Zoo application. No write access to global folders required. This differs from the traditional technique when users install gems and modules globally into the system. The console can be called from the Helicon Zoo Manager using Start web console button or from the project’s template start page. For security reasons only local or authenticated requests are allowed. Server administrators can restrict console access either globally or for individual web sites using Helicon Zoo Manager.

   

5. Helicon Zoo Manager now include CHM documentation. Please use this documentation as we’ll prepare it’s online version soon. To open it use Help –> View help.
6. Philosophy of applications has changed significantly to obtain better portability and isolation in shared environment. Now to start new application or host existing application users need to use Templates in Zoo –> Templates. You just install template for desired application technology and then use web console to configure application as normally. A quick start instruction will be provided on the projects home page. For existing applications you simply copy existing files into application template’s folder, keeping existing files intact. To use third party IDE it is recommended to start it from Helicon Zoo Manager using Start IDE button while the developed application is selected. In this case IDE will be started in pre-configured environment to work with application local folders and to store modules and components inside application. Most current IDEs support this technique to configure folders, but when started separately they will try to install everything globally by default. While it is still possible for some applications to download and install missing components into the application local folder during Helicon Zoo Application Deployment process we recommend to start IDE using Helicon Zoo Manager. More articles with use cases and instructions will be available soon.

   

7. The new ability to start IDE of your choice pre-configured for current application environment directly from Helicon Zoo Manager. You can configure individual IDE for each application. The IDE will be started in the application environment, configured to run scripts using exactly the same interpreter as used for Zoo application, installing modules and components inside application folders, etc. Most current IDEs support this technology. 
8. Helicon Zoo applications are easily portable. If the application is based on Helicon Zoo Template and developed using our guidelines, the only requirement you need to host it on another server is to have corresponding Hosting Package installed on this server using Zoo feed. By installing one of the Hosting Packages you are allowing whole class of web applications to be hosted on a server. Users who has their applications running with Zoo in their development environment can easily push their applications to production servers just by copying web site folders. Even more, different versions of Ruby, PHP, Python, all other technologies available form Helicon Zoo feed can easily coexist on the same server without any conflicts. And users can switch their applications between different versions of PHP or Ruby just by switching engines. Web application portability has never been easier.

   

Currently Helicon Zoo 3.0 is a release candidate and still evolving. This version will be fully compatible with previous one, which means all old applications installed with Helicon Zoo 2.x will continue to work with version 3.0 but some rarely used engines and templates will be deprecated. If your existing system rely on Helicon Zoo 2.x feed we strongly recommend you to test your system against version 3.0 RC as it will be a main release within a week.

• request and response headers,
• cookies,
• server variables,
• environment variables,
• merged httpd.conf and .htaccess files,
• Ape debugging log messages with maximum verbosity.

Debugger shows verbose information not only for successful requests (status code 200), but also all others: redirects 3xx, client-side errors 4xx, server errors 5xx.

This debugger allows you to connect to a remote server and read debug information live. Only your session requests will be presented in the debugger window so other user requests will not be affected. This means you can run debugging in production environment.

Launching the debugger

To run the debugger mod_developer module should be enabled. The following line in  httpd.conf should be uncommented to ensure this:

LoadModule developer_module   modules/mod_developer.so

Then:

• run Helicon Ape Manager
• select the site or application to debug
• select Tools –> Start Ape Debugger
  

The result will be the following:

• a new browser window will open with the site or application selected for debugging; you’ll be able to browse the pages, perform AJAX-requests etc.
• the Debugger tab will be opened in Ape Manager and will show the requests log.

Functionality

The Debugger tab shows the log of all your requests to the site or application being debugged. The log includes the following info about each request: the path, status code, content-type and processing time in IIS.

Click on the line in the log and you’ll see detailed information about the request: request and response headers, cookies, server variables, environment variables, applied httpd.conf and merged .htaccess rules, corresponding error.log and rewrite.log records (if there are any for that request).

Headers:

.htaccess:

Logs:

The log with all debugging info may be opened directly in browser by clicking on the link ‘Open in browser’. Clicking ‘Clear log’ will remove all log entries.

To stop debugging click ‘Stop debugging’ or in Ape Manager choose Tools –> Stop Ape Debugger.

Security

The security of the debugging process is ensured as follows.

When debugging starts the following record is put in .htaccess:

SetEnv mod_developer secure-key-XXXXXXXXXXX

where XXXXXXXXXXX is a secret randomly-generated key for access to debugging info. Upon the first request to debugging session the browser will send this key to the server and will get a cookie with this key and the id of the debugging session. All requests to the server with this cookie are logged. The same cookie is owned by web-interface of debugger  (which is shown in Debugger tab). As a result, only authorized clients (browser and debugger) are allowed to make requests to be logged and receive them.

Upon termination of debugging (click on ‘Stop debugging’) the request to the server is sent and session id and all related log records are deleted. The cookie is reset. The previous cookie left in the browser becomes invalid, the logging stops.

Remote debugging

You can start .htaccess debugging on a server remotely. To do this you need to first put the line which sets mod_developer secure key into .htaccess file on your remote web site.

SetEnv mod_developer secure-key-XXXXXXXXXXX

where XXXXXXXXXXX is any random numbers or text. Then open browser and type a link like this:

http://www.example.com/developer/_ape_start_developer_session?ape_debug=secure-key-XXXXXXXXXXX 

and use same value for XXXXXXXXXXX as you used in .htaccess file. This will start debugger window with “Waiting for data” message. This window also sets special cookie in the browser to identify your debugging session. Now open new tab in same browser and navigate to your web site. You will be reading debug information in the debug session window as you navigate through your web site live.

Configuring Helicon Zoo

First we need to get Microsoft Web Platform Installer and configure it with Helicon Zoo:

1. Download and install Web Platform Installer.
2. Run Web Platform Installer and click “Options”.
3. Add Helicon Zoo feed into “Display additional scenarios” box: http://www.helicontech.com/zoo/feed. New “Zoo” tab will appear.

If it is a development machine it is convenient to choose IIS Express as a target web server for installations. For production environment please choose IIS.

Installing ContentBox CMS

In Web Platform Installer go to Zoo –> Applications, select ContentBox, click Add and then Install:

On a clean system installation may take a while as many components needs to be download and installed. These components usually include: Oracle JDK, Jetty, Railo, Helicon Zoo. Web Platform Installer may also install IIS or IIS Express and WebMatrix if they where not installed before. After installation of all required components is completed if you have selected IIS Express as target web server, the web site with ContentBox will be launched automatically. If you have selected IIS, then you will need to complete the form, choosing a location for new application – this could be application folder inside existing web site or a new web site.

On the first launch of web site you will see the Application deployment in progress page, with the progress of downloading and installing ContentBox CMS files.

It will then refresh automatically to the ContentBox installation wizard:

If you don’t have a database server you can use Web Platform Installer, to install MS SQL Server Express, MySQL or PostgreSQL on your system.

Since we’ve just created new Railo application the Railo Web Administrator password is not set yet. You need to navigate to the Railo web administrator page to set it. Use the URL like this: http://localhost:54973/railo-context/admin/web.cfm Here the host name and port may vary depending on where you have installed ContentBox CMS.

After completing ContentBox installation wizard you should see the web site up and running:

Helicon Zoo is a solution to host web applications written on multiple technologies inside Microsoft IIS and as regular IIS web sites. These technologies include: PHP, Perl, Java, Ruby, Python, Node.js, Erlang and ColdFusion. And when we say, for example, Ruby we mean everything-Ruby. This includes Ruby on Rails, Sinatra, Thin, Goliath, simple Rack or FastCGI applications, etc. The same variety applies to other technologies like Java, Python, etc. Add here native IIS support for ASP and ASP.NET and you’ll get the most technology-packed hosting service available.

All these technologies can be installed on the same server, shared by all users and even mixed within one web site. Consider, for example, users may have their main web site content running on ASP.NET, blog made with WordPress (PHP), forum on DjangoBB (Python), online chat with Node.js, Git repositories with Java, helpdesk solution with Perl and e-commerce solution with Ruby on Rails – all running within the same IIS web site on the same server. Sounds hardly possible? Well, this is nearly how Helicon Tech web site works. Below please find instructions on how to set the same technology on your hosting.

Installing components

Helicon Zoo is delivered as a custom Microsoft Web Platform Installer repository, so all parts of the solution can be installed from one place and you can be sure that everything is tightly integrated and tested to work together.

New WebsitePanel 2.0 includes support for Web Platform Installer and Helicon Zoo repository is also enabled by default. So if you are using this hosting control panel, you need to simply select the server where you wish to install components and click on Web Platform Installer in the Server tools menu.

This will open Web Platform Installer interface where you can install many useful tools and components on your server, like MySQL, MongoDB, PostgreSQL and various IIS components like WebDeploy, URL Rewrite, etc. But we are here to install web application engines. In the Packages tab you can find complete and ready to use hosting packages for various web technologies.

Each of these packages includes everything needed to host applications of specific technology on your server and thanks to Web Platform Installer all required dependencies will be detected, downloaded and installed automatically. So select for example PHP Hosting Package, Java Hosting Package and Ruby Hosting Package and click install, then accept licenses and this will start installation process.

To install Java Hosting Package you will need to download and install Oracle JDK 7. Unfortunately, Oracle prohibits direct downloads of Java packages, this means we cannot include JDK into our repository and you will have to go to Oracle web site and run JDK installation manually. Other packages will install dependencies automatically. Ruby package, for example, includes Ruby 1.8, Ruby 1.9, Ruby DevKit, Thin, Sinatra, Goliath and of course Ruby on Rails 2 & 3, plus it depends on IIS itself and Helicon Zoo Module.

If you don’t plan to use WebsitePanel 2.0 to manage your server you can install Helicon Zoo hosting packages using Microsoft Web Platform Installer. Simply add this feed in Options dialog and install packages you need: http://www.helicontech.com/zoo/feed/

After installation is completed your server is ready to run selected technologies immediately. No other components or configurations are necessary. If you need to configure engines further or restrict customer access to some engines or maybe create custom configurations for running web applications, please read the next chapter.

Configuring Helicon Zoo

Helicon Zoo was designed with shared hosting environment in mind and is capable of functioning in a fully automatic mode. It delivers concept of web engines and applications: where web application is something that resides within user’s web site folder and that is executed by web engine, while web engines are declared globally by server administrator and are located in applicationHost.config. Each engine declares commands, options and environment settings which are used to execute application of particular technology. Hosting users can’t change engines; they can only run applications using them.

There is no need to enable Helicon Zoo engines anywhere after installation. The concept is the same as you normally expect from PHP or ASP applications – simply put the application files into the web site folder and they run. But with Helicon Zoo these files also include web.config file which is used to actually configure the application in a folder, so user web.config files should be enabled for this concept to work.

Applications are executed in the context of IIS Application Pool. This means that if you run each user’s web site in a dedicated Application pool (which is default in WebsitePanel), each application is executed in an isolated user’s environment and with restricted permissions. When user creates a web site or application and uses Helicon Zoo new backend application will be created.

Helicon Zoo can talk to backends using FastCGI or HTTP protocols. “Backends” are for example php.exe or ruby.exe processes. Helicon Zoo will manage backend processes automatically. By default one backend process is started for each application when IIS application starts. Helicon Zoo can then increase the number of backend workers as the load to the application increases to keep response times within reasonable boundaries. It will then shut down excessive workers automatically as load decreases to save server resources.

Engines are configured in applicationHost.config file as <heliconZooServer> <engines> and <userEngines> sections. If you want to edit some engine settings, copy it’s content from <engines> section to <userEngines> section first as engines section can be overwritten when Helicon Zoo Module is upgraded. You can read more about Helicon Zoo Module configuration in the product documentation.

User scenario

So now we have a web server that supports multiple web application technologies, but how will users actually install their applications to use on your servers? There are several options to do that:

Web Application Gallery

If you have WebsitePanel 2 on your hosting services, users can simply use Web Application Gallery to install applications and application templates for particular web technology. For example, assume that user is going to create new Ruby on Rails application. Since we already have Ruby Hosting Package installed on a server, user will open Web App Gallery:

Select Templates:

Scroll down to the Ruby on Rails project and click Install.

During installation user will have to choose a web site where to install the application and whether to put application into subfolder or web site’s root. After installation is completed application can be launched immediately right from WebsitePanel. After first application launch user can then edit and create files and scripts using normal development techniques for the applications of this type. It will be more convenient to download application files locally and work with them on client’s machine, then uploading files using FTP or WebDeploy.

Helicon Zoo provides templates for various web application technologies. List of these templates is constantly growing and updated. The content of each template project depends on the technology used. These projects usually include configuration files required to run application, some basic folder structure to hold static files, modules, etc., some scripts for application deployment and other useful components. We strongly recommend to use these application templates as a starting point for application development as these templates already include pre configurations and patterns for best development experience. If users already have some applications they want to host on your services, they can use application template available with Web Application Gallery to create a new application and then overwrite files in the template by the files of their actual application.

Web Platform Installer and WebMatrix

Another option for the user is to use Web Platform Installer to create a new application or template. The first thing to do here is to get Web Platform Installer from Microsoft. In Options add Helicon Zoo repository feed and select IIS Express as a target web server.

After that user can install any of the Hosting Packages on the client machine and get exactly the same environment as installed on a remote server that will run these applications online. Or user can bypass this step and install project template (like Ruby on Rails project) without installing hosting package, as all required components to run this application template will be downloaded and installed automatically, including WebMatrix and IIS Express itself. This will not probably allow user to run other types of Ruby applications, but the selected applications will run as expected.

After installation is completed WebMatrix will be launched running web application and providing file editors. It is possible to use Visual Studio or any other preferred web application IDE to work with these files.

Then use WebDeploy, FTP access or any other convenient way to upload application to the remote server.

Helicon Zoo applications are normally portable – you can move application from one machine to another simply by copying web application’s folder content, and as long as corresponding Hosting Package is installed on both machines application will run. Obviously if the application connects to a database or other remote services, this has to be taken into account.

One more thing to remember is folder permissions. With IIS Express and WebMatrix applications are usually executed with local user’s permissions (which has full permissions to the application folder), but on remote server applications are run in a restricted environment. Most of the applications require Write permissions to the web site folder for various reasons – write logs, store data, cache, intermediate pre-compiled scripts, save additional modules and components. We recommend enabling Write permissions for entire web site or application folder unless you know exactly which folder permissions should be given to your particular application. Insufficient Write permissions is the most frequent cause of the application failure. With WebsitePanel you can enable Write permissions in the web site’s security options.

Custom modules

The application template is installed and running but what happens if we need to install something more complex than a “Hello world” app? Many applications require additional modules to run. With Helicon Zoo we now have a concept where all modules and requirements of the application are installed inside the application work folder, which is usually user’s web site folder.

Previously web hosting administrators had to install a number of modules globally on the server and maintain up-to-date versions of every component, but with growth of web technologies variety, when new modules and versions are released every day, this becomes an overwhelming task. Different applications may require different versions of components and some of these components may conflict with each other. There definitely has to be a way to isolate application environments. Most modern web application frameworks support an ability to isolate applications and Helicon Zoo actively uses this technique. Each application template project available from Zoo repository includes code examples of how to install modules and components into local application folders.

Users have to be aware of these techniques and appropriate documentation has to be available. For example for Python applications users need to list all application dependencies in the requirements.txt file, instead of installing components globally on the development machine. This is a standard technique for application deployment and all components listed in these requirements.txt files will be installed automatically by deployment script. Users only need to understand that they have no permissions to install components on the server, instead they need to install everything inside the application folder.

Is it safe?

Frequent question from hosting providers – is it safe to allow users to install their custom components? The short answer is: there’s not more threat than allowing users to run their custom (PHP/ASP) scripts. Helicon Zoo executes everything in the context of IIS Application pool, there are no privileged processes or something that users can hack to gain more permissions than they already have. If you restrict permissions for IIS users on your hosting, then running custom modules is the same as running custom scripts on sites. Modules are installed inside user’s web site folder and executed with App pool permissions, no other user environment or global server settings can be affected.

Application deployment

One of the highly important features of Helicon Zoo is Application deployment. Complex applications usually require executing some operations before they could be launched on a server. These operations may include check for installed modules and their versions, download and installation of missing requirements, executing database scripts for data migrations, initialization of application files configurations and data structures. All these operations have to be executed outside of the main application context and before first request to the application will be handled.

Helicon Zoo provides means to execute deployment tasks on a remote server without having RDP or command line access and in restricted user environment. For example if you install one of the web applications available from Zoo repository, like Redmine or DjangoBB, you will see the “Application deployment in progress” message on the first request to the web site:

This application deployment process actually installs the application. You can see as various modules (gems) are installed, as database is created and configured, etc. And all these steps are taken in a local user’s environment with restricted user’s permissions. These application deployment scripts can configure only things inside web application folder or other resources available to user, but they are safe because they cannot change global components or write into shared or system folders.

Web application templates also include deploy script examples which can be used in the client’s applications. To learn more about application deployment with Helicon Zoo please read this documentation chapter.

Advantages of Helicon Zoo over existing solutions

Some of the web engines listed in this article can be executed on Windows and IIS without Helicon Zoo services. PHP is traditionally installed on IIS using Microsoft FCGI module, Node.js can run as a separate server or can be configured using iisnode, ColdFusion server supports Windows platform and can proxy sites into IIS using Jakarta connector. We don’t count other old solutions, like running apps as ISAPI modules (PyISAPIe) or executing scripts with CGI protocol as these solutions can’t be treated seriously because of their very poor performance. Here is a list of reasons why we think Helicon Zoo solution is better for providing shared hosting services:

• Unified environment. Helicon Zoo is a single tool to run all these technologies and it provides single administration point.
• Ability to run multiple technologies and versions on the same server and even same web site. For example you may have PHP 5.2, 5.3 and 5.4 installed and used on the same server at the same time.
• Better isolation. Every application is executed in the restricted environment with credentials of application pool user. There are no privileged processes (like with traditional ColdFusion). No data, processes or settings are shared between different hosting users.
• Custom modules. Users can have their custom modules installed into the application directory. No pain for administrators to maintain modules on the server. Additionally PHP users may have their custom php.ini files to configure PHP engine for their needs.
• Automatic process management. Backend processes are created and recycled automatically to satisfy demand of the application and free resources for other users when possible.
• Slow client optimization. With growth of the number of slow mobile clients this problem is becoming more significant. Synchronous web engines (like PHP) are very vulnerable to unbuffered slow connections and this vulnerability is often used as a DOS attack. Helicon Zoo buffers client communications protecting backends from slow connection problems.
• Application deployment. Ability to execute deployment tasks without having command line or RDP access to the server.

Other things to consider

Many free and open source web applications where designed with Apache environment in mind as it is currently the most popular web server, especially when it comes to open source. While Helicon Zoo provides environment for running numerous applications on IIS, you can make application fall into thinking that it is executed on Apache by emulating Apache environment inside IIS. Helicon Ape product does exactly this thing by bringing support for .htaccess and .htpasswd files and emulating most Apache modules inside IIS environment.

These modules are very useful, not only for URL rewriting, proxying or permission control. There are usage scenarios that can improve user experience significantly. Consider, for example, following articles illustrating some basic applications of Helicon Ape product:

• Search Engine Friendly (SEF) URLs for phpBB – doing search friendly URLs for phpBB with only several rules while phpBB does not support SEF URLs at all.
• Make your websites work faster – with caching and performance improvements.
• IIS reverse proxy and load balancer with web admin panel.
• Counting downloads from your site – how to make comprehensive counters for specific resources.
• Enabling site authentication not using Windows users.
• Prevent DoS attacks with Helicon Ape mod_evasive module.
• Protecting image gallery with Helicon Ape mod_hotlink.

Conclusion

Integration of Helicon Zoo and WebsitePanel is constantly improving. Our future plans are to integrate web application engines management into WebsitePanel interfaces. So the administrators will be able to choose which web engines users are allowed to run and manage restrictions in hosting plans. While it is possible to do this now by manually editing applicationHost.config files, web interface can significantly improve administrator performance. Users will also be able to turn web engines on or off for particular locations which can also add flexibility to the solution.

We will upgrade this article as new things come out and new questions get answered. Please stay tuned. You can read more articles about Helicon Zoo here.

While other companies invest hundreds of thousand dollars into development of their own cloud management solutions, you can already benefit from using free and powerful solution for running web applications on your facilities.

Please send your feedback to our support service or community forum.

To host WSGI-applications with Microsoft IIS 7+ web server there is a unique and free solution – Helicon Zoo. Helicon Zoo in general is an integration platform to run multiple technology stacks in Microsoft IIS web servers.

Installing Helicon Zoo & template WSGI application

To ease process of installing various web server products and technologies we are going to  Microsoft Web Platform Installer. At first let’s download and install Web Platform Installer from it’s official page. Then launch it:

click Options and in «Custom Feeds» box enter http://www.helicontech.com/zoo/feed/ , click «Add feed» and then «Ok»:

Then go to Zoo -> Packages and install Python Hosting Package:

The installation process may take time and will install all required products and engines to host various Python web applications on your server:

After installation is completed your server will be ready to host Python applications simply as any normal IIS web sites. This is really that easy.

Now we are going to create an application to host. There is a collection of project templates in Helicon Zoo feed which you can use as a starting point. Go to Zoo –> Templates and install Python WSGI project.

As you can see, when using WebPI to install project template additional dependencies can be also installed/upgraded. So if you where planning to create one WSGI project you can start right from installing Python WSGI project template instead of installing Python Hosting Package and all required dependencies for this single project will be installed anyway.

After download and install is completed you will be asked to configure WSGI-application. In our case we simply choose a name by which it will be available under Default Web Site:

After all the browser will navigate automatically to the start page for application. This is simple stub page with service information.

How it works?

Helicon Zoo Module is a native IIS 7+ module which acts as a bridge between web server and application on Python, Ruby, Perl, Node.js and other languages. This module uses FastCGI or HTTP protocol to transfer requests from web server to backend application and get responses to the client. This is asynchronous process that utilizes I/O Completion Port technology to provide highest performance and maximum capacity. Additionally Helicon Zoo Module manages backend applications, starts and stops them automatically based on a current service load and overall server resources. It sets appropriate environment for backend applications to run and monitors their health to provide instant and reliable service for all clients.

Configuration directives in web.config file of the IIS web site can be used to change some Helicon Zoo Module settings and configure appropriate environment for the application. Here is web.config example:

<?xml version="1.0" encoding="UTF-8"?>
<configuration>
  <system.webServer>
    <heliconZoo>
      <application name="WSGI.project" >
        <environmentVariables>
          <add name="PYTHONPATH" value="%APPL_PHYSICAL_PATH%;%APPL_PHYSICAL_PATH%\python_modules\Lib\site-packages;%PYTHONPATH%" /> 
          <add name="DEPLOY_FILE" value="deploy.py" />
          <add name="ERROR_LOG_DIR"  value="log" />
          <add name="WSGI_APP" value="wsgi.application" />
        </environmentVariables>
      </application>
    </heliconZoo>
    <handlers>
      <add name="WSGI.project#x86" scriptProcessor="python.2.7.wsgi"
           path="*" verb="*" modules="HeliconZoo_x86" preCondition="bitness32" resourceType="Unspecified" requireAccess="Script" />
      <add name="WSGI.project#x64" scriptProcessor="python.2.7.wsgi"
           path="*" verb="*" modules="HeliconZoo_x64" preCondition="bitness64" resourceType="Unspecified" requireAccess="Script" />
    </handlers>
  </system.webServer>
</configuration>

Here you can see two handlers declaration for 32 or 64 bit IIS processes that will call appropriate version of Helicon Zoo Module. Each handlers sets script processor to “python.2.7.wsgi” which instructs Helicon Zoo to use Python WSGI engine to run this application. Names of the handlers minus #suffix are used to identify additional settings for the application in the <heliconZoo> section. There you can define various environment variables that will be set in backend environment and are used to pass additional parameters to Helicon Zoo Module and application itself. Here are some of possible variables:

• PYTHONPATH – is a path where Python will look for it’s modules and additional files. Here we add current web site physical folder and python_modules\Lib\site-packages folder with modules.
• DEPLOY_FILE – name of the deploy script file that will be called on every application start. Usually there are instructions in this file to install required modules, do database migrations and other deployment things.
• DEPLOY_LOG – a path to the log file where to save deploy script output. If this variable is not set deploy script output will be sent to the client’s browser.
• ERROR_LOG_DIR – a folder where to store various application and error logs. 
• WATCH_FILE_CHANGES_MASK – set this variable to the file mask, like “*.py” and backend application will be restarted when any *.py file inside web site is changed. Useful in development environment. 
• WSGI_APP – a python path to the WSGI application to run. In our case this would be a wsgi.py file in the website root with an application function in it.

We will be using a magnificent free and open source tool – SCM-Manager. This is simple and nifty looking manager tool for Git, SVN and HG written in Java. Probably the best thing about SCM-Manager is that it includes all dependencies inside and does not require you to download and compile any third party components. You don’t have to install Git or any other kind of servers to host repositories. It does require Python and Hg package to host Mercurial repositories, but these packages can be installed automatically into the SCM-Manager home directory directly form web interface. So if your host support hosting of Java applications you don’t need access to the server console to install some components or run additional commands.

Hosting Java applications with Helicon Zoo

First of all you need to configure your IIS server to host Java applications. The easiest way to do this is to use Web Platform Installer.

1. Download and install Microsoft Web Platform Installer.
2. Run Web Platform Installer and click “Options”.
3. Add Helicon Zoo feed into “Display additional scenarios” box: http://www.helicontech.com/zoo/feed. New “Zoo” tab will appear.
4. Go to the Zoo –> Templates and select Java (Jetty) project.
5. Accept licenses to start installation process.

This will install all dependencies required to run Java application on IIS, including JVM, Helicon Zoo Module, etc. After installation of all dependencies is completed you will be presented with the standard Web Deploy dialog to create new web application:

Select “New web site” in the web site field and configure other options as usual.

Another good way to install all required dependencies is to install Zoo –> Packages –> Java Hosting Package. This package is usually installed on servers to allow them to host Java applications. The idea is that Java application can be simply moved from one IIS server to another just by copying web site folder, if both servers has Java Hosting Package installed.

Installing SCM-Manager

First you need to download SCM-Manager as a single WAR file here: https://bitbucket.org/sdorra/scm-manager/wiki/download Save this WAR file to the IIS web site folder and edit web.config file as follows:

<?xml version="1.0" encoding="UTF-8"?>
<configuration>
  <system.webServer>
    <heliconZoo>
      <application name="jetty.project" >
        <environmentVariables>
          <add name="CONTEXT_PATH" value="%APPL_VIRTUAL_PATH%" />
          <add name="WAR_EXTRACT_PATH" value="%APPL_PHYSICAL_PATH%" />
          <add name="WAR_FILE" value="scm-webapp-1.20.war" />
          <add name="SCM_HOME" value="%APPL_PHYSICAL_PATH%/.scm" />
        </environmentVariables>
      </application>
    </heliconZoo>
    <handlers>
      <add name="jetty.project#x86" scriptProcessor="java.jetty"  path="*" verb="*" modules="HeliconZoo_x86"
           preCondition="bitness32" resourceType="Unspecified" requireAccess="Script" />
      <add name="jetty.project#x64" scriptProcessor="java.jetty"  path="*" verb="*" modules="HeliconZoo_x64"
           preCondition="bitness64" resourceType="Unspecified" requireAccess="Script" />
    </handlers>
  </system.webServer>
</configuration>

Here the WAR_FILE environment variable contains the downloaded WAR file name. The SCM_HOME points to the /.scm folder under web site home, this will instruct SCM-Manager to store all files and repositories inside a web site folder. Note that write permissions to the web site folder for the user running Web Application Pool are required.

Now navigate to the web site created. The first start usually takes some time as SCM-Manager will create files and folder structures, configurations and Java Virtual Machine also needs time to start-up. After application initialization you should see a login screen. Enter the following default credentials to log in:

login: scmadmin
password: scmadmin

Don’t forget to change default password later. Now welcome to the dashboard:

Working with SCM-Manager

After installation you can immediately start creating empty Git and SVN repositories. To start using Hg open Repository Types page under config section and start Configuration Wizard for Mercurial. Select “download and install” and required packages will be installed into /.scm folder under web site automatically.

More often users ask how to import your existing repositories into SCM-Manager. All repositories are stored in the folder /.scm/repositories inside your web site. If you have FTP access to these folders you can simply copy entire directory structure of your repositories to the corresponding folders under /.scm/repositories. For SVN this is the only viable option to import repository as it uses central repository storage. Then click on Import Repositories link on the dashboard and your repositories will be imported into SCM-Manager.

Since Git and Hg uses decentralized repository storage, you can simply create empty repositories with web interface and then push your local repositories to the new location.

Now you can create users and groups, manage permissions, view commits and sources. And the most important feature of SCM-Manager is that it provides central point to administer all of your repositories from different source controls on a remote servers and over internet. And it is so easy to start work with!

Environment installation

First we need to configure the Windows server to run CFML applications. Please follow these instructions:

1. Download and install Microsoft Web Platform Installer.
2. Run Web Platform Installer and click “Options”.
3. Add Helicon Zoo feed into “Display additional scenarios” box: http://www.helicontech.com/zoo/feed. New “Zoo” tab will appear.
4. Go to the Zoo –> Engines and install Railo 3 or Railo 4 (or both).

   

   Alternatively you can install Zoo –> Packages –> CFML Hosting Package. This will install both Railo 3 and 4 and all other requirements to host CFML applications on IIS.

   

5. Accept licenses to start installation process.

All required packages and dependencies will be downloaded and installed. Whole installation process may take time. After installation is completed your server is ready to run CFML applications as usual IIS web sites.

Usage

To create new Railo web site you can use Web Platform Installer again. Go to Zoo –> Templates and install Railo 3 or Railo 4 project.

You can set either IIS or IIS Express as target environment for this project and if you have not installed CFML Hosting Package, then all required dependencies will be installed automatically. After installation is completed Railo web site will start working immediately.

If you want to create Railo web site manually, please add an empty IIS web site for your application:

Create web.config file in the web site folder and put the following content into it:

<?xml version="1.0" encoding="UTF-8"?>
<configuration>
  <system.webServer>
    <heliconZoo>
      <application name="railo.project">
        <environmentVariables>
        </environmentVariables>
      </application>
     </heliconZoo>
    <handlers>
      <add name="railo.project#x86.cfm"   scriptProcessor="railo" 
        path="*.cfm"   verb="*" modules="HeliconZoo_x86" 
        preCondition="bitness32" resourceType="Unspecified" 
        requireAccess="Script" />
      <add name="railo.project#x86.cfc"   scriptProcessor="railo" 
        path="*.cfc"   verb="*" modules="HeliconZoo_x86" 
        preCondition="bitness32" resourceType="Unspecified" 
        requireAccess="Script" />
      <add name="railo.project#x86.cfml"  scriptProcessor="railo" 
        path="*.cfml"  verb="*" modules="HeliconZoo_x86" 
        preCondition="bitness32" resourceType="Unspecified" 
        requireAccess="Script" />
      <add name="railo.project#x86.cfr"   scriptProcessor="railo" 
        path="*.cfr"   verb="*" modules="HeliconZoo_x86" 
        preCondition="bitness32" resourceType="Unspecified" 
        requireAccess="Script" />
      <add name="railo.project#x86.cfswf" scriptProcessor="railo" 
        path="*.cfswf" verb="*" modules="HeliconZoo_x86" 
        preCondition="bitness32" resourceType="Unspecified" 
        requireAccess="Script" />
      
      <add name="railo.project#x64.cfm"   scriptProcessor="railo" 
        path="*.cfm"   verb="*" modules="HeliconZoo_x64" 
        preCondition="bitness64" resourceType="Unspecified" 
        requireAccess="Script" />
      <add name="railo.project#x64.cfc"   scriptProcessor="railo" 
        path="*.cfc"   verb="*" modules="HeliconZoo_x64" 
        preCondition="bitness64" resourceType="Unspecified" 
        requireAccess="Script" />
      <add name="railo.project#x64.cfml"  scriptProcessor="railo" 
        path="*.cfml"  verb="*" modules="HeliconZoo_x64" 
        preCondition="bitness64" resourceType="Unspecified" 
        requireAccess="Script" />
      <add name="railo.project#x64.cfr"   scriptProcessor="railo" 
        path="*.cfr"   verb="*" modules="HeliconZoo_x64" 
        preCondition="bitness64" resourceType="Unspecified" 
        requireAccess="Script" />
      <add name="railo.project#x64.cfswf" scriptProcessor="railo" 
        path="*.cfswf" verb="*" modules="HeliconZoo_x64" 
        preCondition="bitness64" resourceType="Unspecified" 
        requireAccess="Script" />
    </handlers>
    <defaultDocument>
      <files>
        <remove value="index.cfm" />
        <add value="index.cfm" />
      </files>
    </defaultDocument>
  </system.webServer>
</configuration>

This will enable Railo 3 to process requests for the registered file extensions in this IIS web application folder. To use Railo 4 set scriptProcessor=”railo.4″ instead. As there is no currently application files in this folder navigating to the root of the web site will trigger 403 error. So please navigate to the http://localhost/railo-context/admin.cfm to open Railo administration interface. For the first start you will be asked to create server and web administrator passwords.

After that you may just put your CFML application into this IIS web site folder.

Manual installation

Sometimes you may need to install specific version of Railo, or you may only want to install Railo for a specific IIS web site instead of installing it on a server globally. There could be a case when your hosting service does nto provide Railo support, but instead has support for generic Java applications. In this situation please follow this instruction:

If you are installing on your own server first you need to follow first three steps from “Environment install” chapter to get Helicon Zoo feed in Web Platform Installer. Now go to Zoo –> Packages and install Java Hosting Package. This will install support for generic Java applications for IIS.

Then go to the Railo Download page and get the WAR archive distribution version. Put this WAR file into IIS web site root folder and create a web.config file there with the following content:

<?xml version="1.0" encoding="UTF-8"?>
<configuration>
  <system.webServer>
    <heliconZoo>
      <application name="jetty.project" >
        <environmentVariables>
          <!-- Uncomment line below if you want to set contexts directory -->
          <!--  <add name="CONTEXTS_DIR" value="%APPL_VIRTUAL_PATH%" /> -->

          <!-- Optional variables: -->
          <!-- <add name="CONTEXT_PATH" value="%APPL_VIRTUAL_PATH%" /> -->
          <!-- <add name="WAR_EXTRACT_PATH" value="%APPL_PHYSICAL_PATH%" /> -->

          <!-- A WAR file or start directory to run -->
          <add name="WAR_FILE" value="railo-3.3.1.000.zip" />
        </environmentVariables>
        </application>
    </heliconZoo>

        <handlers>
          <add name="jetty.project#x86" scriptProcessor="java.jetty" 
            path="*" verb="*" modules="HeliconZoo_x86" 
            preCondition="bitness32" resourceType="Unspecified" 
            requireAccess="Script" />
          <add name="jetty.project#x64" scriptProcessor="java.jetty" 
            path="*" verb="*" modules="HeliconZoo_x64" 
            preCondition="bitness64" resourceType="Unspecified" 
            requireAccess="Script" />
        </handlers>
  </system.webServer>
</configuration>

Note the name of the file here is railo-3.3.1.000.zip. You may need to change it if your version of Railo is different. Also as you can see handlers are mapped to the asterisk – “*”, which mean every request to this web site will be processed by Java, including static files. Sometimes this is a good idea, especially if you are using some kind of URL rewriting or request filtering tools in your Java or CFML application. We have chosen to use asterisk map as it is more generic and will provide better application compatibility. But if you feel confident in server configuration, mapping handlers to specific file extensions (as it is done in web.config from automatic installation chapter) will give you some performance points, as static files will be processed directly by IIS.

Now you can navigate your browser to the web site root, which will bring you Railo welcome page. Then simply put your CFML application in this IIS web site folder to start working with Railo!

Environment installation

First we need to configure our Windows server to run Java Servlet applications. This is easily doable using following instructions.

1. Download and install Web Platform Installer.
2. Run Web Platform Installer and click “Options”.
3. Add Helicon Zoo feed into “Display additional scenarios” box:  http://www.helicontech.com/zoo/feed. New “Zoo” tab will appear.
4. Go to the Zoo -> Packages and install Perl Hosting Package.
5. Accept licenses to start installation process.

After installation is completed your server is ready to run Perl applications using either FastCGI or Plack/PSGI protocol. Perl Hosting Package includes Strawberry Perl and some other modules, like CPAN Minus, etc.

Creating Perl Dancer web site

For the beginning create a new web site or application in IIS Manager. Either IIS or IIS Express are supported. Let’s name this site “dancer” and folder for it will be “C:\intepub\dancer\”. Now navigate to this folder using command line and run following commands in it:

cpanm -n -L .\perl Dancer

Installation process may take time and after it we will have Dancer compiled and installed with all dependencies in the “C:\intepub\dancer\perl” folder. Local installation is preferable as when you’ll need to deploy your application to the production server your site will have no dependencies, except for Perl Hosting Package from Helicon Zoo.

Now let’s create new Dancer application and call it “mysite”. This is done with the following two commands in the same location:

set PERL5LIB=.\perl\lib\perl5\
perl\bin\dancer.bat -a mysite

After site is created we need to provide write permissions to the  “C:\intepub\dancer\mysite\logs\” folder. Dancer requires this permissions to run. Since we already have command line open in the right location, let’s use Windows “icacls” tool for it. Run the following two commands:

md mysite\logs\
icacls mysite\logs\ /t /grant:r "IIS_IUSRS:M"

As the last step we need to create web.config file in the root of the web site – “C:\intepub\dancer\web.config”. Put this code into the web.config file to activate Helicon Zoo for this location:

<?xml version="1.0" encoding="UTF-8"?>
<configuration>
  <system.webServer>
    <heliconZoo>

      <application name="dancer">
        <environmentVariables>
          <add name="APP_WORKER" value="%APPL_VIRTUAL_PATH%mysite\bin\app.pl" />
          <add name="PERL5LIB" value="%APPL_PHYSICAL_PATH%\perl\lib\perl5" />

        </environmentVariables>
      </application>

    </heliconZoo>

    <handlers>
      <add name="dancer#x86" scriptProcessor="perl.5.12.psgi" path="*" verb="*" modules="HeliconZoo_x86"
           preCondition="bitness32" resourceType="Unspecified" requireAccess="Script" />
      <add name="dancer#x64" scriptProcessor="perl.5.12.psgi" path="*" verb="*" modules="HeliconZoo_x64"
           preCondition="bitness64" resourceType="Unspecified" requireAccess="Script" />
    </handlers>

  </system.webServer>
</configuration>

A little portion of magic and we have it all set. Just point your browser to the web site created and you should see a Dancer welcome page:

Platfrom installation

1. Download and install Web Platform Installer.
2. Run Web Platform Installer and click “Options”.
3. Add Helicon Zoo feed into Display additional scenarios box:  http://www.helicontech.com/zoo/feed. New “Zoo” tab will appear.
4. Go to the Zoo, Packages and install Java Hosting Package.
5. Accept licenses to start installation process.

Alternatively, instead of installing Java Hosting Package you can install Modules –> Helicon Zoo Module and Engines –> Jetty separately. This is minimal requirement to run Java Servlet applications under Microsoft IIS web server. If you want to run Java Servlets under IIS Express and WebMatrix in your development environment, then you will also need to install Helicon Zoo Module for IIS Express form Engines section.

This is enough configuration to run most of Java Servlet applications directly form IIS.

Installing application

Launch IIS Manager and create new web-site or an application within a web-site. Copy your Java application into the root folder of this IIS application. Java application could be either a single .war file or set of unpacked files with directory structure, including web-inf folder. Then just create the following web.config:

<?xml version="1.0" encoding="UTF-8"?>
<configuration>
  <system.webServer>
    <heliconZoo>
      <application name="jetty.project" >
        <environmentVariables>
          <!-- Uncomment line below if you want to set contexts directory -->
          <!--  <add name="CONTEXTS_DIR" value="%APPL_VIRTUAL_PATH%" /> -->

          <!-- Optional variables: -->
          <!-- <add name="CONTEXT_PATH" value="%APPL_VIRTUAL_PATH%" /> -->
          <!-- <add name="WAR_EXTRACT_PATH" value="%APPL_PHYSICAL_PATH%" /> -->

          <!-- A WAR file or start directory to run -->
          <add name="WAR_FILE" value="my_application.war" />
        </environmentVariables>
        </application>
    </heliconZoo>

        <handlers>
          <add name="jetty.project#x86" scriptProcessor="java.jetty" 
            path="*" verb="*" modules="HeliconZoo_x86" 
            preCondition="bitness32" resourceType="Unspecified" 
            requireAccess="Script" />
          <add name="jetty.project#x64" scriptProcessor="java.jetty" 
            path="*" verb="*" modules="HeliconZoo_x64" 
            preCondition="bitness64" resourceType="Unspecified" 
            requireAccess="Script" />
        </handlers>
  </system.webServer>
</configuration>

Please take a look at <environmentVariables> section.

• CONTEXTS_DIR — optional path to directory with .xml files which describe Jetty contexts. If this variable isn’t set, Zoo looks for “contexts” folder in the root of application. If no such folder found, Zoo presumes the application has single context and uses variables described below.
• CONTEXT_PATH — optional virtual path of the application. Default value is taken from APPL_VIRTUAL_PATH variable.
• WAR_FILE — optional path to a .war file or directory with extracted application.
• WAR_EXTRACT_PATH — optional .war file extraction path. Is set to application’s root folder by default.

Here is an example of context.xml file that you may use instead of setting WAR file name explicitly. This allows to run multiple applications and contexts in a single IIS web site.

contexts/context.xml

<?xml version="1.0"?>
<!DOCTYPE Configure PUBLIC "-//Jetty//Configure//EN" "http://www.eclipse.org/jetty/configure.dtd">

<Configure class="org.eclipse.jetty.webapp.WebAppContext">

   <Set name="contextPath">/application</Set>
   <Set name="war">my_application.war</Set>
   <Set name="tempDirectory">application_dir</Set>

</Configure>

WARNING: Since WAR files need to be extracted before execution you will need to have a folder with write permissions.  In default IIS installation all application pools are executed with permissions of IIS_IUSRS group which does not have write permissions to the web application folders. You will need to provide write permissions to the user running Application Pool or IIS_IUSRS group to the folder containing Java application or specify other folder using WAR_EXTRACT_PATH variable with write permissions provided.

Now you can open IIS web site in the browser and see your Java web application running.

That’s it! Installation process is clear and automatic and will only take several minutes.