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.

Here are the steps to accomplish this:

1. Find a hosting with IIS7 on it.
2. Download Helicon Ape to your local machine. Not to the hosting!
3. Install it locally specifying «Manual package» in the Installation type dialog.
   
4. Open Helicon Ape installation folder (e.g. “C:\Program Files\Helicon\Ape\ManualInstall”).
5. Open target site via FTP and go to wwwroot folder.
   
6. Copy all content of ManualInstall folder into wwwroot (preserving folder structure). “All” includes:
   – Bin\Helicon.Ape.dll – the module itself;
   – Helicon\httpd.conf – server configuration file;
   – .htaccess – distributed config example;
   – example_web.config – Helicon Ape registration for the site;
   If there’s no web.config in the root of the site, rename example_web.config into web.config. If web.config is already there, add the following lines into <system.webServer> section:

   <?xml version="1.0" encoding="UTF-8"?>
   <configuration>
      ...
      <system.webServer>
        ...
        <modules>
           <add name="Helicon.Ape" type="Helicon.Ape.ApeModule" />
        </modules>
        <handlers>
           <add name="Helicon.Ape Handler" path="*.apehandler" verb="*"
                type="Helicon.Ape.Handler"
                resourceType="Unspecified" preCondition="integratedMode" />
        </handlers>
      ...
      </system.webServer>
    ...
   </configuration>

7. Open wwwroot\.htaccess and put the following lines at the bottom to check operability:

8. RewriteEngine On
   RewriteRule . – [G]

9. Make any request to your site and you are likely to get the following result
   

   Which means that Helicon Ape is working!

Possible issues

“But it isn’t actually working!” you exclaim indignantly.
This may be due to several possible reasons:

1. Firstly, let’s have a glance at wwwroot\Helicon\error.log.
   
2. In our case the hosting has restricted permissions in a way that doesn’t allow Ape to use its trial protection, so it is necessary to enter the registration data. Ask for trial keys on [email protected], add the following lines at the top of wwwroot\Helicon\httpd.conf and save changes:

   RegistrationName= Name
   RegistrationCode= XXXXX-XXXXX-XXXXX-XXXXX

   
3. There may also be issues with your distributed configuration. .htaccess files may be used by other applications (such as ISAPI_Rewrite, IISPassword, etc) and it’s not that handy to create them in Windows Explorer. Luckily you are empowered to change the default config name using AccessFileName directive in the httpd.conf file:

   AccessFileName Ape.ini

   
4. Sometimes hosting configures the site to work in Classic pipeline mode. Ape can work in such environment (see how to configure wildcard mapping) but it’s better to ask your hosting to switch the pool to Integrated mode if possible.
5. It may happen that hosting has set too low .Net Trust Level for the site. This may affect Helicon Ape operation.
   

   Full down to Medium level is sufficient for Ape to work a treat. Lower level may cause substantial limitations.

   

Resume

As you see configuring Helicon Ape on shared hosting is piece of cake! And no administrator help is needed. You can do everything by yourself in a matter of minutes.
Hope this feature will be of use to you.

Good luck and best wishes,
Helicon Tech Team