Helicon Zoo Module configuration

To separate web server administrator configurations from webmaster/user configurations we have developed the concept of engines and applications. Engine is a declaration of what can be executed and how and they can only be configured by server administrator in applicationHost.config file. Application define usage of particular engine in the IIS web site or application context and can be set either in applicationHost.config or in web.config file.

applicationHost.config

Engines are declared in the <heliconZooServer> section of applicationHost.config using <engines> or <userEngines> tags. Each engine sets properties, like command line arguments, protocol or transport to run specific web engine. The <userEngines> collection is used to override engines or create new ones, if you need to preserve these settings during Helicon Zoo Module upgrades. Helicon Zoo installation wil not modify or delete <userEngines> section. So if you need to change some pre-defined engine create a copy of it inside <userEngines> collection first. Here is an example of applicationHost.config sections:

<?xml  version="1.0" encoding="UTF-8"?>
<configuration>
 <system.webServer>
  <heliconZooServer>
   <engines>
       <add name="ruby.1.9.pipe"
             fullPath="%SystemDrive%\Ruby19\bin\rubyw.exe"
             arguments="%SystemDrive%\Zoo\Workers\ruby\zack.rb"
             transport="NamedPipe"
             protocol="fastcgi"  />
       <add name="nodejs.http" 
             fullPath="%SystemDrive%\node\bin\node.exe"
             arguments="&quot;%APP_WORKER%&quot;"
             transport="tcp"
             protocol="http" >
          <environmentVariables>
            <add name="APP_WORKER" value="%APPL_PHYSICAL_PATH%\server.js" />
            <add name="NODE_PATH" value="%APPL_PHYSICAL_PATH%\node_modules" />
            <add name="WATCH_FILE_CHANGES_MASK" value="*.js" />
          </environmentVariables>
       </add>
    </engines>
    <userEngines>
       <add name="php.5.2.pipe" displayName="Php 5.2 fastCgi" fullPath="%ProgramFiles(x86)%\PHP\v5.2\php-cgi.exe"
            arguments="-c &quot;%PHP_INI%&quot;" transport="NamedPipe" protocol="fastcgi">
          <environmentVariables>
             <add name="ERROR_LOG_DIR" value="NULL" />
             <add name="WATCH_FILE_CHANGES_MASK" value="php.ini" />
             <add name="PHP_INI" value="%ProgramFiles(x86)%\PHP\v5.2\php.ini" />
             <add name="PHP_FCGI_MAX_REQUESTS" value="100000" />
          </environmentVariables>
       </add>
    </userEngines>
  </heliconZooServer>
 </system.webServer>
</configuration>


This is the list of all possible attributes of engine with explanations:

  • name – sets a name for the engine.
  • fullPath – a path to a worker executable file.
  • arguments – set of arguments to be passed to a worker on a call, can include special environment variables, see below.
  • deployArguments – optional set of arguments to be passed to a worker on a call to deploy script.
  • protocol – possible values “fastcgi” or “http”.
  • transport – possible values “namedpipe” or “tcp”.
  • portLower – specifies lower bound for automatic port range for TCP transport, default = 49152.
  • portUpper – specifies upper bound for automatic port range for TCP transport, default = 65535 (different engines can share same port region).
  • minInstances – minimum number of worker instances. Zoo will pre-start this amount of instances even if there’s no load to the server, default = 1
  • maxInstances – maximum number of instances of worker processes to start under high load. Default value of 0 means start as many instances as there are cores.
  • postBuffer – maximum size of a memory buffer used to temporarely store request post data. Useful to protect against slow post DDOS attacks. default = 1024 (kilobytes). Use postBuffer="0" to disable buffering post requests.
  • timeLimit – restart the worker after it has worked for specific amount of time (minutes), default = 0 (infinite).
  • memoryLimit – restart the worker if it has consumed specific amount of memory (megabytes), default = 0 (unlimited).
  • gracefulShutdownTimeout – time given to worker to finish all current requests and shutdown gracefully, otherwise it will be killed after this timeout, default = 30 (seconds).


Aditionally to parameters you can specify environment variables. These variables will be available in web engine's environment and can be used as additional parameters to specific applications or engine specific settings.

Some environment variables has special meaning to Helicon Zoo Module. Some are used to pass application specific parameters to Zoo Module, others are set by Zoo Module to pass some application specific data to web engines.

Here is the list of environment variables set by Helicon Zoo Module that will be available to engine's worker:

  • APPL_PHYSICAL_PATH – a physical path to IIS application (web site) being called.
  • APPL_VIRTUAL_PATH – virtual path to IIS application being called.
  • HOST – usually 127.0.0.1.
  • PORT – port number assigned to this worker call form available ports range.


This is the list of environment variables you can set to confiugure application specific settings in Zoo Module:

  • POST_BUFFER – same as postBuffer in engine's attributes. 1024 kilobytes by default.
  • POST_CACHE_DIR – you can define an application specific directory, to store temporary POST data in files, if size of data is larger than POST_BUFFER parameter. If POST_BUFFER is set to zero (0) this parameter is ignored and POST requests are not buffered by Zoo.
  • CURRENT_DIRECTORY – a start up directory for worker application; default is %APPL_PHYSICAL_PATH%.
  • ERROR_LOG_DIR – relative path to a directory where log files to be stored. Value of "NULL" disables logging.
  • WATCH_FILE_CHANGES_MASK – file mask to watch for file changes and restart workers if change is made. Example: "*.js".
  • DEPLOY_FILE – script file name that will be called when application needs to deploy. Engine's script processor is used to call this script. Path is Application Root-relative, example value="deploy.rb" - for Ruby applications. After deploy process is finished the deploy file will be renamed as "filename_done.ext" to prevent subsequent call to this script. Rename file back to start deploy again. See application deployment for more information.
  • DEPLOY_LOG – file to store deploy script console output. If this parameter is not set deploy output will be shown to any client requesting the web site during deploy.
  • WORKER_REQUEST_TIMEOUT – smart worker request timeout; default = 30 (seconds). Helicon Zoo will try to "ping" backend if no response was provided during this timeout. If no response to the "ping" provided, "500 Timeout error" is reported to the client and backend worker is restarted. If "ping" is responded Zoo continues to wait for next timeout period. Therefore if backend hangs it will be restarted, but long polling and websocket communications will work without changing this smart timeout value.


In engine attributes like fullPath or arguments you can reference environment variables using %VARIABLE_NAME% syntax and environment variables set in web.config files can also be referenced there.

Here is the list of all engines currently declared in applicationHost.config which you can use in your application:

python.2.7.pipe
python.2.7.wsgi
python.2.7.http 
python.2.7.twisted 
ruby.1.8.rack 
ruby.1.8.http 
ruby.1.9.rack 
ruby.1.9.http 
ruby.2.0.rack 
ruby.2.0.http 
php.5.2.pipe 
php.5.3.pipe 
perl.5.12.pipe 
perl.5.12.psgi
nodejs.http
railo
railo.3
railo.4
java.jetty
java.jetty.8
java.appdir
java.appdir.8
zotonic.http

web.config

After declaring engines in applicationHost.config you can use them in web.config to initiate an application in specific location. Here is web.config section example:

<?xml version="1.0" encoding="UTF-8"?>
<configuration>
 <system.webServer>
  <heliconZoo>
   <application name="rails.project" >
    <environmentVariables>
     <add name="DEPLOY_FILE" value="deploy.rb" />
     <add name="DEPLOY_LOG" value="log\zoo-deploy.log" />
     <add name="RACK_ENV" value="development" />
    </environmentVariables>
    <fastcgiVariables>
     <add name="SCRIPT_NAME" value="%APPL_VIRTUAL_PATH%"  />
    </fastcgiVariables>
   </application>
  </heliconZoo>
  <handlers>
       <add name="rails.project#x86" scriptProcessor="ruby.1.9.rack"
          path="*" verb="*" modules="HeliconZoo_x86"
          preCondition="bitness32" resourceType="Unspecified"
          requireAccess="Script" />
       <add name="rails.project#x64" scriptProcessor="ruby.1.9.rack"
          path="*" verb="*" modules="HeliconZoo_x64"
          preCondition="bitness64" resourceType="Unspecified"
          requireAccess="Script" />
  </handlers>
 </system.webServer>
</configuration>

In <heliconZoo> section you can set or owerride environment variables for this application. Name of application used in <heliconZoo> section should be the same as the name of appropriate handler in <handlers> section except for the optional #suffix. The #x86 or #x64 suffix is used to decalre different handlers for 32 or 64 bitness modules since web.config syntax requires every handler to have unique name. Helicon Zoo will ignore these suffixes so you can have only one <application> settings section for two handlers. The example above decalres two handlers which form one application and will be called when IIS is started in appropriate bitness.

Explanation of <handlers><add>tag attributes:

  • name="rails.project#x86" – name of the handler (with optional #suffix) for reference;
  • scriptProcessor="ruby.1.9.pipe" – references name of the engine declared in applicationHost.config to use;
  • modules="HeliconZoo_x86" – 32-bit version of Helicon Zoo Module, for 64-bit version use "HeliconZoo_x64".