hxfcgi

hxfcgi is a rewrite of the haxe Web API to deploy Haxe written web applications in a CGI / FCGI environment. It also gives to the possibility to use the Haxe C++ target as a platform for your web applications.

hxfcgi is quite new and should be considered as experimental. More testing and documentation is required.

Differences to the Haxe Web API

  • If you using FastCGI you should use Web.cacheModule(), otherwise the module will be restarted after every request, which is quite slow.
  • If you using CGI if does not matter if you use Web.cacheModule().
  • You need to print some data, when sending headers only, call Lib.print(""); after setting all headers.

Simple Example


Let's start with a simple example:
#if neko
import neko.Web;
import neko.Lib;
#else
import cpp.Web;
import cpp.Lib;
#end

class Example {

    static function main() {
        Web.cacheModule(run);
        run();
    }
    
    static function run() {
        Web.setHeader("Content-type","text/plain");
        Lib.println(Web.getParams());
    }
}

Neko target


haxe -main Example -lib hxfcgi -D HXFCGI -neko example

Now we need to make the neko bytecode directly executable:
nekotools boot example.n

And rename the file, to be accepted as FastCGI binary (for deployment as CGI module it is recommended add the .cgi extension to the file''):
mv example example.fcgi

Cpp target


haxe -main Example -lib hxfcgi -D HXFCGI -cpp example/

Rename the file to be accepted as FastCGI binary (for deployment as CGI module it is recommended add the .cgi extension to the file''):
mv example/Example example.fcgi

Deploying

  • If you deploy an application compiled with the Haxe cpp target to your webserver you need the hxfcgi.ndll to be loadable from the FastCGI process / loadable from the web server process.
  • If you deploy an application compiled with the neko target to your webserver you need the hxfcgi.ndll AND the nekoapi.ndll to be loadable for the nekoVM.

Apache

This next section is just a guide which shows one of many possible ways to deploy the app on your server!

FastCGI:

  • if not, enable fastcgi module (on debian based system: a2enmod fastcgi)
  • your fastcgi.conf should look similar to this one:
    <IfModule mod_fastcgi.c>
      AddHandler fastcgi-script .fcgi
      FastCgiIpcDir /var/lib/apache2/fastcgi
    </IfModule>
  • if you want to use the fastcgi app as an index page add this:
    DirectoryIndex index.fcgi
  • your site config should contain:
    <Directory />
        Options ExecCGI
        AddHandler fastcgi-script fcgi
        AllowOverride All
    </Directory>
  • upload you app.fcgi into you webroot

CGI:

  • if not, enable cgi module (a2enmod cgi)
  • if you want to use the cgi app as an index page add this:
    DirectoryIndex index.cgi
  • copy you file to your script dir
  • or tell Apache to run CGI scripts on you dir:
    <Directory />
        Options +ExecCGI
        AddHandler cgi-script cgi .cgi
        AllowOverride All
    </Directory>

nGinx


TODO

lighttpd

FastCGI:

  • install spawn-fcgi (on debian-based system: "apt-get install spawn-fcgi")
  • upload you index.fcgi and the required ndll files into you webroot
  • launch spawn-fcgi :
    sudo spawn-fcgi -u www-data -s /tmp/myapp.sock  ./index.fcgi
  • for lighttpd 1.4.*
    server.modules += ( "mod_fastcgi" )
    $HTTP["host"] == "myapp.mydomain.cc" {
        [...]
        fastcgi.server = ( 
            ".fcgi" => (( "socket" => "/tmp/myapp.sock"))
        )
    }
  • for lighttpd 1.5.*
    server.modules  += ("mod_proxy_core","mod_proxy_backend_fastcgi")
    $HTTP["host"] == "myapp.mydomain.cc" {
        [...]
        PHYSICAL["existing-path"] =~ "\.fcgi$" {
                    proxy-core.protocol = "fastcgi"
                    proxy-core.backends = ( "unix:/tmp/myapp.sock" )
            }
    }

CGI:

  • copy you file to your dir
  • enable cgi module and declare .cgi extension
    server.modules  += ( "mod_cgi" )
    cgi.assign      += (
        ".cgi" => ""
    ) 

Source code & bugs


The source code of the project could be found here: hxfcgi. If something does not work the way it should work feel free to contribute a patch or simply file a issue.

Building from source


Until now the project have been tested on Linux and Mac. You need the following requisites:
  • hxcpp installed via haxelib (even if you want to deploy to the neko target!)
  • FastCGI header files (even if you want to deploy in CGI mode) [On debian based systems install the package libfcgi-dev]
  • A C++ compiler. Only tested with g++ from the gcc.
  • make sure you have a nekoapi.ndll according to your platform
  • for 64 bits platforms build with "make HXCPP_M64=1"

git clone git://github.com/TheHippo/hxfcgi.git
cd hxfcgi/
make

version #15869, modified 2013-01-28 06:21:02 by ianxm