Skip to end of metadata
Go to start of metadata

Preparing the system

Extracting the WebObjects Runtime

Before you can install the WebObjects Runtime you must first extract the necessary files from the WebObjects Runtime disk image that Apple uses to distribute the software. You will need to use a Mac to do this as the DMG file format is not supported by other platforms.

  1. Fetch the WebObjects 5.3.3 Runtime from Apple's website
  2. Mount the disk image on a Mac and copy the package archive from within the package's Resources folder to the FreeBSD system's ports distfiles directory. Note: The following assumes you have sudo installed on the FreeBSD system
    cd '/Volumes/WebObjects 5.3.3 Developer Update/WebObjects5.3.3Update.pkg/Contents/Resources'
    scp WebObjects5.3.3Update.pax.gz deployment.host:/tmp
    ssh deployment.host sudo mv /tmp/WebObjects5.3.3Update.pax.gz /usr/ports/distfiles
    

    Alternative File extraction technique

    Icon

    It is possible to extract the required package archive from the DMG without mounting it using the following commands.

    dd if=WebObjects5.3.3Update.dmg bs=0x1000 skip=0xb12 of=WebObjects5.3.3Update.pax.gz
    perl -e 'truncate "WebObjects5.3.3Update.pax.gz", 29672581'
    

Updating the FreeBSD Ports tree

The Ports tree for FreeBSD is constantly being updated and it is important that you have updated the local ports tree before proceeding any further.

Use portsnap to update the ports tree

portsnap fetch extract

Installing Java

Java for FreeBSD can be installed either as a package or a port. Either way requires that certain items be downloaded manually, for instructions on downloading and installing the Sun JDK from source visit the FreeBSD Java Project website. The binary JDK distribution for FreeBSD is known as Diablo and is available from the FreeBSD Foundation Java Downloads site. Although WebObjects is certified against JDK 1.4, there are no known issues with using JDK 1.5 and it is suggested that you try this version first.

Installing the Diablo JDK 1.5 port after downloading the necessary distfiles might look something like this:

cd /usr/ports/java/diablo-jdk15
make install

Extracting WOPorts

Download and extract the WOCOM:WOPorts bundle into your home directory

cd ~
tar -zxf woports-20070530.tgz

Installing WebObjects from the ports archive

Icon

Since some time, in /usr/ports/www/webobjects, there is the latest archive. So go there, after you have extracted ebObjects5.3.3Update.pax.gz in /usr/ports/distfiles, and then type
make install
You will get a license:

Do you agree to the above license terms? [yes or no] 
type yes, 
and everything will be installed for you:
*****************************************************************************

The WebObjects Runtime is now installed.

Add wotaskd_enable="YES" and JavaMonitor_enable="YES" to rc.conf as required
and start each application by running:
/usr/local/etc/rc.d/wotaskd start
/usr/local/etc/rc.d/JavaMonitor start

Your WebObjectDocumentRoot has been created in /usr/local/www/webobjects/WebObjects
You will need to direct your webserver to use this path for /WebObjects URI's

Logs for all WebObjects applications can be found in /var/log/webobjects

*****************************************************************************
===> Installing rc.d startup script(s)

Be aware that this does not install all the stuff that the WOCOM:WOPorts bundle installs, like Wonder and the apache adaptors.

Installing a web server

If you intend to setup a WOAdaptor front end on the machine then it is recommended you install the web server of your choice first. Currently supported web servers are Apache, nginx and lighttpd.

To install Apache 1.3 + SSL you would do this:

cd /usr/ports/www/apache13-ssl
make install

To install Apache 2.2 (which always includes SSL) you would do this:

  1. cd /usr/ports/www/apache22
    make install
    
  2. Edit /etc/rc.conf and add the following lines:
      apache22_enable="YES"
    

Installing the WebObjects Runtime

Configure & Install the WebObjects Deployment port

The WebObjects Deployment port allows you to automatically install the webobjects runtime as well as a variety of WebObjects related dependencies. These include WOAdaptors for Apache and CGI/FastCGI, JDBC & EOF plugins (for FrontBase, PostgreSQL, MySQL & OpenBase), Project Wonder and WOProject.

You can configure your preferred options and install the port like this:

#cd ~/ports/www/webobjects-deploy
#make config

               Options for webobjects-deploy 1.0
          [X] APACHE         Install Apache Module Adaptor
          [ ] WOADAPTOR      Install Web Server CGI Adaptor
          [X] FASTCGI          FastCGI support
          [X] EOACCESS       Install EOF Database Plugins
          [X] FRONTBASE        FrontBase support
          [X] POSTGRESQL       PostgreSQL support
          [X] MYSQL            MySQL support
          [ ] OPENBASE         OpenBase support
          [ ] WONDER         Install Project Wonder
          [ ] APPLICATIONS     Applications Bundle
          [ ] EXAMPLES         Examples Bundle
          [ ] DOCS             Documentation Bundle
          [ ] WONDERNIGHTLY    Use Wonder from Nightly Builds
          [ ] WONDERCVS        Use Wonder from CVS
          [ ] WOPROJECT      Install WOProject Ant tasks
          [ ] WOLIPSNIGHTLY    Use WOProject from Nightly Builds
          [ ] WOLIPSSVN        Use WOProject from Subversion
          [ ] COMPILE        Compile from source where available

#make install

Configuring JavaMonitor & wotaskd

To use JavaMonitor and wotaskd you will need to configure them to run on startup.

Edit /etc/rc.conf and add the following lines:

JavaMonitor_enable="YES"
wotaskd_enable="YES"

To run them manually without rebooting do the following:

/usr/local/etc/rc.d/wotaskd start
/usr/local/etc/rc.d/JavaMonitor start

Even if you run them manually, you still need to add the lines above to the /etc/rc.conf.

Configuring the web server

Apache

If you are using Apache as your front end, and have installed the WebObjects Apache module, you will need to make some minor modifications to the standard configuration to make things work.

  1. Comment out the ScriptAlias /cgi-bin/ statement
    The standard apache config comes with a ScriptAlias to allow /cgi-bin/ scripts to be run, this interferes with the default webobjects config so you will want to disable it.
  2. Include the webobjects.conf file
    If you are using Apache 1.3 add the following line to the end of your /usr/local/etc/apache/httpd.conf file:
    Include /usr/local/etc/apache/webobjects.conf
    
    If you are using Apache 2.2 the configuration file will already be installed in the following location:
    /usr/local/etc/apache22/Includes/webobjects.conf
    
    You will need to edit it for your specific installation. In particular, you may need to change WebObjectsAlias from /cgi-bin/WebObjects to /Apps/WebObjects or else Apache gets confused. The easiest way to do this is to replace 'cgi-bin' throughout the webobjects.conf file with 'Apps'.

Nginx

If you are using nginx as your front end, and have installed the FastCGI adaptor, you will need to add the following declaration to the server configuration in order to enable the adaptor.

        # WebObjects Adaptor config
        location /cgi-bin/WebObjects {
            set $path_info   "";
            set $script_name /cgi-bin/WebObjects;
            if ($fastcgi_script_name ~ "^/cgi-bin/WebObjects(/.+)$") {
              set $path_info $1;
            }
            fastcgi_param PATH_INFO   $path_info;
            fastcgi_param SCRIPT_NAME $script_name;
            fastcgi_pass  unix:/tmp/woadaptor.sock;
            include       fastcgi_params;
        }

        location /WebObjects {
            root   /usr/local/www/webobjects;
        }

You will also need to enable the FastCGI service to run on startup by adding the following line to /etc/rc.conf

woadaptor_enable="YES"

Lighttpd

If you are using lighttpd as your front end, and have installed the FastCGI adaptor, you will need to add the following declaration to the server configuration in order to enable the adaptor.

fastcgi.server = ( "/cgi-bin/WebObjects" =>
  ( "WebObjects" => (
    "socket"          => "/tmp/woadaptor.sock",
    "check-local"     => "disable",
    "bin-path"        => "/usr/local/libexec/WebObjects-fcgi",
    "bin-environment" => (
      "WO_CONFIG_URL" => "http://localhost:1085",
      "WO_ADAPTOR_INFO_USERNAME" => "userhere",
      "WO_ADAPTOR_INFO_PASSWORD" => "passhere",
    )
 ))
)

alias.url = ( "/WebObjects/" => "/usr/local/www/webobjects/" )
$HTTP["url"] =~ "^/WebObjects($|/)" { dir-listing.activate = "disable" }

Verify the Installation

Apache

With no additional applications installed, you should be able to test part of your installation now. This assumes that you have Apache configured properly.

apachectl start
/usr/local/etc/rc.d/wotaskd start
/usr/local/etc/rc.d/JavaMonitor start

Then with a web browser, visit http://HOSTNAME:56789/. The JavaMonitor application should appear. You should immediately set a password for the JavaMonitor if you do not have some other mechanism in place for restricting access to this application.

To shut down manually:

/usr/local/etc/rc.d/JavaMonitor stop
/usr/local/etc/rc.d/wotaskd stop
apachectl stop

Deploying an Application

The traditional method for deploying a WebObjects application is to do a split install. This involves installing the application bundle into one location, and the web server resources into another.

Installing the application

Installing the application bundle is simply a case of transferring the application to the appropriate location on the deployment server. This might look something like this:

scp -rp MyTestApp.woa deployment.host:~/MyTestApp.woa
ssh deployment.host
cd /usr/local/apple/Local/Library/WebObjects/Applications
sudo mv ~/MyTestApp.woa .
sudo chown -R www:www MyTestApp.woa
sudo chmod 755 MyTestApp.woa/MyTestApp

Installing the web server resources

Next you need to install any web server resources that belong to your application. If you have a separate bundle already with just these resources you can just copy the bundle directly into /usr/local/www/webobjects/WebObjects like we did with the application bundle previously. If you don't have a separate split install bundle you can install the necessary files this way:

cd /usr/local/apple/Local/Library/WebObjects/Applications
find MyTestApp.woa -path '*/WebServerResources/*' | sudo cpio -dumpl /usr/local/www/webobjects/WebObjects
cd /usr/local/www/webobjects/WebObjects
sudo chown -R www:www MyTestApp.woa

Installing Wonder

Project Wonder is installed into Local/Library/Frameworks (not Library/Frameworks).

The steps below assume that you have installed the 'curl' utility and that you are running as root.

cd /usr/local/apple/Local/Library/Frameworks/
curl -O http://webobjects.mdimension.com/wonder/Wonder-latest-Frameworks-53.tar.gz
tar xvfz Wonder-latest-Frameworks-53.tar.gz