Jaxer in Aptana Studio

To simplify the development process, Aptana Studio includes Jaxer and you don't need to separately install or uninstall Jaxer. These instructions are for installing Jaxer on a machine on which Studio isn't or when a separate instance is desirable and generally speaking do not apply to using Jaxer inside Studio. All the other pages in this guide, except where explicitly noted, apply equally to using Jaxer standalone or in Studio.

Download and Install

First download Jaxer

OS-specific Installation Instructions

• Windows: Unzip the download to the folder where you want to install Jaxer (see expected results).
• OS X: Launch the DMG and drag the Aptana_Jaxer folder to the Applications folder. Jaxer can reside inside other folders, if needed for your purposes. (see expected results).
• Linux: Detailed instructions

Samples and Tools: Bundled applications can be found in <Jaxer install folder>/jaxer/aptana

Updating to a New Version of Jaxer

The standard Studio update process will let you know there's a newer version of Jaxer for Studio available.

For the standalone Jaxer Package:

1. Stop Jaxer if it's running.
2. Delete the jaxer folder inside your Aptana Jaxer (or Aptana_Jaxer or AptanaJaxer) folder.
3. Download Jaxer_update.zip and unzip it into your Aptana Jaxer (or Aptana_Jaxer or AptanaJaxer) folder, which creates a new jaxer folder.

All your data and settings will be preserved as they aren't kept in the overwritten folder.

Use Jaxer with an Existing Apache

Jaxer installs its own Apache instance, which should not interfere with an existing Apache install. However, should you prefer to use Jaxer with an existing Apache instance, Jaxer comes with OS-specific httpd.conf files for Linux, Windows and OS X. You should use the version for your operating system, including it with and include directive in the main Apache httpd.conf; including the file instead of copying the contents into the main conf file means changes and updates will be much simpler. These files are located in the <Jaxer install dir>/jaxer/confs folder.

Windows: You'll need to edit the supplied conf file to enter path information specific to your installation; all the places requiring change can be found by searching the file for the string ${ and replacing the placeholder starting from the $ character and including the open and close braces and the string in between with the correct values. The specific tokens are:

• ${ANCHOR}: the root directory of your install, the folder in which you unzipped the Jaxer package
• ${WINDIR}: the Windows install dir, i.e. C:\Windows
• ${JAXER_WEB_PORT}: the port on which Jaxer listens for connections from the web server; its displayed by Jaxer on startup: JaxerManager 1.0.3.4544 (web 4327, command 4328)

Mac OS X: On this platform mod_jaxer is compiled as a 32 bit executable. If you are running a 64-bit Apache you need to recompile mod_jaxer to 64 bit mode, then copy the resulting .so file into /Applications/Aptana_Jaxer/jaxer/connectors. Grab the Jaxer Connectors source code first!

1. Switch to mod_jaxer folder in exploded source: cd ~/Downloads/1.0.0.4310/products/server/src/connectors/apache/apache-modules/mod_jaxer
2. Compile: /usr/sbin/apxs -Wc,-arch -Wc,ppc64 -Wl,-arch -Wl,ppc64 -c -Wc,-arch -Wc,x86_64 -Wl,-arch -Wl,x86_64 -c -o mod_jaxer.so *.c
3. Copy: cp .libs/mod_jaxer.so /Applications/Aptana_Jaxer/jaxer/connectors
4. Restart Apache: sudo apachectl graceful

Using Jaxer with WAMP or XAMPP

Methodology used in developing these instructions: download the WAMP or XAMPP package, install and test that it works, grab the Jaxer update (you don't need the Apache stuff for this) and then wire that into the default WAMP/XAMPP install. These instructions are Windows-specific, the key difference for OS X and Linux are to use the conf file and paths appropriate for your OS.

1. Unzip the contents of jaxer_update.zip to your WAMP/XAMP's bin directory (e.g., C:\wamp\bin\jaxer or C:\xamp\jaxer)
2. Copy jaxer\confs\jaxer-win.httpd.conf to C:\wamp\bin\apache\apache2.2.8\conf\extra or C:\xampp\apache\conf\extra
3. Include the Jaxer conf in C:\wamp\bin\apache\apache2.2.8\conf\httpd.conf or C:\xampp\apache\conf\httpd.conf:

   Include conf/extra/jaxer-win.httpd.conf

4. Replace all the ENV tokens in jaxer-win.httpd.conf with actual paths (as described in the Windows Apache note previously)
5. Create the required jaxer folders inside the C:\wamp or C:\xamp folder:
   • logs
   • local_jaxer
   • local_jaxer\conf
   • local_jaxer\data
   • local_jaxer\extensions
6. Copy the default contents from C:\wamp\default_local_jaxer\conf to C:\wamp\local_jaxer\conf (or C:\xamp\default_local_jaxer\conf to C:\xamp\local_jaxer\conf)
7. Verify the installation (C:\wamp\bin\apache\apache2.2.8\bin\httpd -t or C:\xamp\apache\bin\httpd -t)

As the install location chosen is inline with the filesystem layout and different from the regular Jaxer setup, the logs and local_jaxer folders are not in the standard location as a peer of the Jaxer folder, so we need to make a few changes to the shipped scripts. Edit bin\jaxer\StartJaxer.bat and change the following settings:

# As shipped
if not defined JAXER_LOG_OUTPUT set JAXER_LOG_OUTPUT=%~dp0\..\logs\jaxer.log
if not defined JAXER_TEMP set JAXER_TEMP=%~dp0\..\tmp
if not defined JAXER_CFG set JAXER_CFG=%~dp0\..\local_jaxer\conf\JaxerManager.cfg
		
# WAMP values
if not defined JAXER_LOG_OUTPUT set JAXER_LOG_OUTPUT=%~dp0\..\..\logs\jaxer.log
if not defined JAXER_TEMP set JAXER_TEMP=%~dp0\..\..\tmp
if not defined JAXER_CFG set JAXER_CFG=%~dp0\..\..\local_jaxer\conf\JaxerManager.cfg

The conf and extension folder locations are defined in jaxer\framework\config.js and you need to change those references, in this case by changing the relative path to point one folder further up the tree:

LOCAL_CONF_DIR: ('LOCAL_CONF_DIR' in Jaxer.Config) ? Jaxer.Config.LOCAL_CONF_DIR : "../../local_jaxer/conf", // It may have been set before this point, if you're in Jaxer Framework dev mode
LOCAL_EXTENSIONS_DIR: ('LOCAL_EXTENSIONS_DIR' in Jaxer.Config) ? Jaxer.Config.LOCAL_EXTENSIONS_DIR : "../../local_jaxer/extensions",

Finally, start Apache, run bin/jaxer/StartJaxer.bat and open http:/localhost/aptana in your web browser.

At this point WAMP/XMP and Jaxer should be running together. If you want to serve content through the default www folder you'll need to add the Jaxer processing directives to that entry in the base C:\wamp\bin\apache\apache2.2.8\conf\httpd.conf or C:\xamp\apache\conf\httpd.conf file.

Preview Jaxer Apps in Studio with an External Server

Once you've set up Jaxer to work with an external web server such as Apache, WAMP, XAMP or similar, you can configure Aptana Studio to take advantage of it for previews while you develop your applications. This requires a few configuration changes.

1. Edit the web server conf file to allow it to process documents from your Aptana Studio workspace.
2. In Studio, configure the preview preferences for your project. The following instructions assume you want to set up a workspace project called myProj to be served through a WAMP instance:
   1. Right click myProj in the Project browser and choose Preferences
   2. Select the HTML Preview panel
   3. Check the Override workspace settings checkbox
   4. Select Use absolute URL as the Preview Type
   5. Enter the URL for the project (http://localhost/studio/myProj)
   6. Check the Append project relative path checkbox
   7. Click Apply, then OK
3. Create a new conf file, for example named jaxer-workspace.httpd.conf, with the following content in the web server's conf\extra folder. <Directory "C:\path\to\your\workspace"> JaxerFilter .html .xhtml .htm .php JaxerFilterContentType text/html Order Deny,Allow Allow from all </Directory> Alias /studio "C:\path\to\your\workspace"
4. Add this line to your server's conf\httpd.conf file: Include conf/extra/jaxer-workspace.httpd.conf

After you restart the Apache daemon, requests to http://localhost/studio/<PROJECTNAME> will now served by your server.

Set up Jaxer as a Service/Server

For production or even very heavy development phases you may prefer to have Jaxer running at all times rather than launching it manually, as described in the next section. You should understand that Jaxer must be started separately from Apache, configuring mod_jaxer alone is not sufficient.

Running Jaxer as a service on Linux and OS X is no different from how you normally launch Jaxer except that you must set up a mechanism to ensure Jaxer runs when the computer is on.

Also on Linux and OS X only, the user as which Jaxer runs must have write permissions on certain folders, especially for log files and folders in which any files the application itself writes are stored.

Windows

We include command line arguments in JaxerManager to install and uninstall Jaxer as a service, as well as start service and stop service commands. You can pass the full set of command line configuration options with the Install argument.

JaxerManager -i[nstall] [JaxerManager options]
JaxerManager -u[ninstall]
JaxerManager -s[tart]
JaxerManager -stop

OS X

This OS does not include a simple tool for ensuring certain applications run constantly so we recommend you consider using a free, open source utility called Lingon. Lingon is a graphical user interface for creating an editing launchd configuration files written by Peter Borg. You can use launchd on a Mac to launch scripts and applications whenever something special happens or at a specific time or periodically.

As shown in this image, to configure Lingon you simply enter a name (e.g., com.aptana.jaxer), the full path to the start script supplied with Jaxer (/Applications/Aptana_Jaxer/scripts/start.sh) and check the Run at startup or login option.

Linux

This is one area in which the distros differ greatly. We will post the more popular (among Jaxer developer community) distros but if you have instructions for another one please post it to the Installing and Configuring Jaxer forum and we'll add it here.

Ubuntu and Red Hat

Note: These instructions should work for Ubuntu and other Debian-based distros and Red Hat and its kin, however, the further away you get... Slackware is apparently an example of too far away.

• touch /etc/init.d/jaxer
• chmod +x /etc/init.d/jaxer
• open /etc/init.d/jaxer and copy in the following script

#!/bin/sh
#
# Aptana Jaxer initscript
#
case "$1" in
	start)
		echo "Starting jaxer..."
		/opt/AptanaJaxer/scripts/start.sh
		echo "Jaxer started."
		 ;;
	stop)
		echo "Stopping jaxer..."
		/opt/AptanaJaxer/scripts/stop.sh
		echo "Jaxer stopped."
		 ;;
	force-reload|restart)
		/opt/AptanaJaxer/scripts/stop.sh
		echo "Jaxer stopped."
		/opt/AptanaJaxer/scripts/start.sh
		echo "Jaxer successfully restarted."
		 ;;
	*)
		echo "Usage: /etc/init.d/jaxer {start|stop|restart|force-reload}"
		exit 1
		 ;;
esac
exit 0

You can now start, stop, or restart Jaxer by running

/etc/init.d/jaxer {start|stop|restart}

Using the Service command

To control Jaxer using the service command, run service jaxer {start|stop|restart}. Red Hat includes the service command, on Ubuntu sysvconfig must be installed: apt-get install sysvconfig -y.

Auto-launching Jaxer

To set your server so Jaxer runs automatically at startup time, refer to the distro specific instructions in the following list.

• Ubuntu/Debian: update-rc.d jaxer defaults
• Red Hat, SUSE: two commands, chkconfig jaxer --add and then chkconfig jaxer on --level 2,3,5
• Gentoo: rc-update add jaxer default

Launching Jaxer

• Windows: Open the Aptana Jaxer folder, double-click StartServers.bat and open http://localhost:8081 in a web browser
• OS X: Open the Aptana_Jaxer folder (inside Applications), and double-click the Jaxer Launcher
• Linux: In a terminal window run /opt/AptanaJaxer/scripts/start.sh and in a browser open http://localhost:8081/aptana/

Launching starts Jaxer, JaxerManager and the Apache server, displays the Jaxer console, and opens the Jaxer Start Page in your default web browser.

On OS X you also get the Jaxer Launcher window.

First Run

The first time Jaxer runs several folders are created in <Jaxer install dir> directory.

Validate Your Installation

Click the Server Diagnostics link in the sidebar to run the diagnostics application. Good install results will look like this:

Additional diagnostics

• Components diagnostics: Runs the Jaxer server unit test suite to help identify any subsytem issues
• jQuery Compatibility: Runs the jQuery test suite

Content Visibility

Content placed inside the Aptana Jaxer/public directory is accessible from the root of the web server. For example, the contents of a folder named test will be accessible from at http://localhost:8081/test/.

Uninstalling Jaxer

Delete the <Jaxer install dir> folder.

Troubleshooting

Port not available

This error message occurs when a Jaxer package starts up and attempts bind to a port number already in use by another server or application, most commonly another instance of Apache. The Apache default port is 8081 and the Jaxer defaults are 4327 (used for Apache to talk to Jaxer) and 4328 (CLI port for talking to JaxerManager, also used by Aptana Studio).

The three ports can be set in StartServers.bat on Windows and in <Jaxer install dir>/scripts/StartJaxer.sh on Linux and OS X, preferably just after the JAXER_LOG_OUTPUT setting; on OS X the default Apache port can be changed on the Jaxer Launcher preferences dialog.

set JAXER_APACHE_PORT=80
set JAXER_WEB_PORT=4327
set JAXER_COMMAND_PORT=4328

Linux Dependencies

If you're running a server or headless version of Linux and Jaxer will not start you're most likely missing certain required X/graphical libraries (our standards-based Mozilla core has dependencies although there is no actual rendering on screen); the simplest solution is to install Firefox using your distribution's package manager:

• Fedora: yum install firefox-devel
• Debian: apt-get install firefox-devel

Dependencies not found

The ldd command displays the Jaxer dependencies which could not found - which you may then install using the package manager:

export LD_LIBRARY_PATH=/opt/AptanaJaxer/jaxer
ldd /opt/AptanaJaxer/jaxer/jaxer

CentOS 5.1 Issues

On CentOS 5.1 if you see a stream of "Jaxer creation failed" messages when running start.sh from the command line, then you may need to install the sqlite and firefox-devel packages:

yum install sqlite
yum install firefox-devel

Fedora 8 Issues

On Fedora 8 if you get an error message about a missing libexpat.so.1 library, then you will need to create a symlink where libexpat.so.1 points to libexpat.so.0.

ln -s /lib64/libexpat.so.0 /lib64/libexpat.so.1

Out of Memory

If the Jaxer server crashes with an "Out of Memory" exception, you may have to increase the memory defaults. A simple way to do this would be to set no maximum limits for the Jaxer process. Run this command before starting Jaxer:

ulimit -s unlimited

Jaxer is not defined error

If you see this message, check that your Jaxer server is running. If you're inside Aptana Studio, the Jaxer toolbar button should be showing the green light and if it's not click the toolbar button to restart Jaxer server. For standalone Jaxer, follow the Launch instructions for your operating system.

Could not set System.homeFolder

On some system configurations, an error may be logged during startup when Jaxer tries to determine the location of the home folder. This may be caused by an invalid or erroneous setting for the HOME environment variable. Make sure that the HOME environment variable references a location that is both a valid folder and is accessible to the user running Jaxer. This error can be ignored; however further attempts to use the Jaxer.System.homeFolder property will result in additional instances of the exception being written to the logs.