C++ objects container running on Linux. A light-weigth and pure C++ alternative for servlet containers

Cobra documentation

If you want to see what's needed by Cobra, look at requirements. To build needed stuff go to installation instructions. When you have installed all stuf you'll probably want to look at configuration instructions.

1. Requirements

  • Unix with support for dynamic loading (dlopen and so on, modern Linux is good enough)
  • Web server with FastCGI support. Apache and mod_fastcgi is a good choice
  • libfcgi from www.fastcgi.com
  • 2. Installation

    To make your life easier here are some instructions how to prepare your box to work with Cobra.

    2.1 Apache + mod_fastcgi

    These instructions assume we're building from sources so download latest version of Apache sources. Use one of 1.3+ series as guys from FastCGI recommend. Best place to start with is httpd.apache.org. You will also need mod_fcgi which you can get from www.fastcgi.com

    Now it's time to have some fun with building

    assumption: we use apache-1.3.29 and mod_fastcgi-2.4.2 If you want to use other versions change some numbers in commands below

    1. unpack tarballs
    tar -xzf apache_1.3.29.tar.gz
    tar -xzf mod_fastcgi-2.4.2.tar.gz
    
    2. Copy mod_fastcgi distribution directory to apache source tree
    cp mod_fastcgi-2.4.2 apache_1.3.29/src/modules/fastcgi -dpR
    
    3. Build apache
    cd apache_1.3.29
    configure --activate-module=src/modules/fastcgi/libfastcgi.a
    make
    make install
    
    Last command you have to type from root account

    2.2 libfcgi

    First of all download source of libfcgi from www.fastcgi.com

    assumption: we use libfastcgi-2.4.0 If you want to use other versions change some numbers in commands below

    Here's the instruction what to do with the tarball

    1. Unpack it
    tar -xzf libfcgi-2.4.0.tar.gz
    
    2. Build the thing
    ./configure
    make
    make install
    
    Pretty hard, huh? Don't forget to execute last command as root

    2.3 Cobra

    1. Go to download section to get latest version of Cobra sources.
    2. unpack Cobra tarball
    tar -xzvf Cobra-0.0.1.tar.gz
    
    3. Build and install Cobra
    cd cobra-0.0.1.tar.gz
    make all
    make install
    
    Now you've done it! cobra binary is in /usr/local/cobra/bin

    3. Configuration

    3.1 Apache + mod_fastcgi

    Since Cobra talks to web through FastCGI interface you need to enable it in your webserver's config. Also you have to tell your webserver how to connect to Cobra and where Cobra objects are seen by web users.

    Add this lines to httpd.conf
    # web interface for first application
    FastCGIExternalServer /hello -host 127.0.0.1:4001
    ScriptAlias /hello /hello
    
    <Location   /hello>
        SetHandler fastcgi-script
        Options FollowSymLinks MultiViews ExecCGI
        AllowOverride None
        Order allow,deny
        Allow from all
    </Location>
    
    # ... and for the second
    FastCGIExternalServer /info -host 127.0.0.1:4002
    ScriptAlias /info /info
    
    <Location   /info>
        SetHandler fastcgi-script
        Options FollowSymLinks MultiViews ExecCGI
        AllowOverride None
        Order allow,deny
        Allow from all
    </Location>
    

    3.2 Cobra

    Cobra configuration file may look like this
    # This is first application
    [ application ]
      port = :4001
      object = /usr/src/cobra/examples/hello/hello.so
    
    # ... and the second one
    [ application ]
      port = :4002
      object = /usr/src/cobra/examples/info/info.so
    
    Above configuration states that cobra is running two applications. Each application has its own port for web server to connect to. These ports numbers are used in web server configuration files.

    4. Running

    After boring process of building from sources and configurating it's time to run the whole thing. First of all start you web server

    assumption: apache is installed in /usr/local/apache
    # /usr/local/apache/bin/apachectl start
    
    If everything went find you should see message saying that "httpd started". Then type this command

    assumption: Cobra is installed in /usr/local/cobra
    $ /usr/local/cobra/bin/cobra /usr/src/cobra/examples/cobra.conf
    
    And the last step is build example applications. If you didn't specified other prefix these applications are located in /usr/src/cobra/examples directory. Try to type this command in each directory:

    assumption: Cobra is installed in /usr/local/cobra
    $ make
    
    You may want to see how to build cobra applications - take a look at Makefiles. Of course you also may want to add some changes to these application. If you want this changes to be visible via web you have to run make and cobra will auto-reload applications if it's needed. If you have any troubles take a look at /tmp/cobra.log file. But remember, better logging is in TODO section, in other words don't expect a lot of info. If you want to stop cobra you can type this command

    $ killall cobra
    
    I'm working on better solution.