Jaxer & XAMPP – JavaScript Bliss

Being that I just started my new job at Aptana, one of the first things they asked me to do is learn everything I can about Jaxer and to document that process. For those of you who don’t know yet, Jaxer is essentially and AJAX server. The very long story short is that you now have the ability to run JavaScript on the server-side (no more cross-site restrictions!), and along with that ability you get some pretty kick-ass API functionality that isn’t normally an inherent part of JS (such as built-in filesystem or database functionality). Essentially, you can now write the better part, if not all of your web apps in JavaScript. What’s even cooler is that you don’t need to give up the technologies that you currently use in order to implement Jaxer. I’ll be writing on how you can blend all these new and existing technologies in the near future (perhaps even make my screen-casting debut), but for now I want to talk about how to get Jaxer set up with an existing Apache install, specifically an XAMPP-based development environment.

Granted you can download a stand-alone Jaxer+Apache bundle, but if you’re like me, you want to be able to start seeing how it plays with existing web technologies (for me, that would be PHP). The other thing that you’ve probably already got (if you’re like me) is a test / development environment locally, and it’s most likely XAMPP (or something similar). Finally, if you’re slightly OCD like me, you like to have everything in one place, all nice and organized. Well, you’re in luck, because I’m going to show you how to get all of this goodness up and running. My examples will be for a Mac install of XAMPP, but the Windows / Linux methods will be pretty darned close. The only caveat with this walk-through is that it is written based on the upcoming 0.9.5 release (which will be out within the next week or so), and this is because it covers some important changes from the 0.9.4 releases. Now that we’ve got all that out of the way, let’s get into how we can get all this up and running. Read on…

Step 1 – XAMPP

There are a lot of nice Apache + MySQL + PHP packages out there, but none of them (in my opinion) are quite as easy as XAMPP. So, head on over to ApacheFriends.org and download the installer for your OS and, well, install it. Once you’ve done that, you’re ready to start installing Jaxer. But, before we do that, let’s take note of a few things:

• The XAMPP Program Root – On OS X, this is

  /Applications/xampp/xamppfiles

  On windows it will be something very similar.

• The Apache Conf File – This is located in

  /Applications/xampp/xamppfiles/etc

  For the uninitiated, the Apache config file is “httpd.conf”. To be honest, if you have never opened this file on any system, this might be a bit over your head, and I would suggest just working with the stand-alone Jaxer+Apache for now. If you’re feeling adventurous, or a quick learner, then read on, this stuff really isn’t rocket science!

We’ll soon be dropping Jaxer into the XAMPP root, and modifying our Apache config… then you’ll be ready to dive into the awesomeness that is Jaxer (seriously, it’s awesome… and no, I’m not getting payed to say that )

Step 2 – Download & Unpack Jaxer

Jaxer is always available at http://www.aptana.com/jaxer/download or bundled in Aptana Studio version 1.1 and higher.

REMEMBER, this walk-through is for version 0.9.5 of Jaxer, which (at the time of writing) will be released within a week or so. I’ll make sure to post when its out, so be sure to subscribe to my feed. Anyway, head on over to the the download link above and grab a copy of Jaxer for your system. Make sure you grab the full version, not the updater. Once its downloaded, we’re going to grab a copy of the Jaxer folder and move it (and some others) over to the XAMPP root. If you’re on the Mac, I would suggest going ahead and installing it (simply drag the Aptana_Jaxer folder to your Applications folder), so you have not only a working copy for reference, but a good place to start over from if you screw up.

OK, so, first, head over to either the package itself or the Jaxer install directory, and copy the whole “jaxer” folder and paste it into the XAMPP root we noted above. Check it out:

Remember that’s the “jaxer” folder inside the “Aptana_Jaxer” package to the

/Applications/xampp/xamppfiles

folder. While we’re at it, we need to grab one more folder and copy it to the same place: “local_jaxer”. If you look in the picture above, you’ll see that I’ve already got it there.

Step 3 – Supporting Directories

We’ve also got to manually create some directories in the XAMPP root. This is where it gets a little different for the Max / Linux users, as we need to also make sure that these directories have write permissions (I just use 777 since this is a local dev environment). Windows users, just create the directories, you’re fine with permissions.

Anyway, the easiest way to get this all done is to open up Terminal (Applications => Utilities => Terminal) and type the following (Linux users, adjust accordingly):

cd /Applications/xampp/xamppfiles
sudo mkdir data
sudo mkdir tmp
sudo chmod 777 logs
sudo chmod 777 data
sudo chmod 777 tmp

Jaxer needs the logs directory, but the latest XAMPP comes with one there already, so we only need to make sure it can be written to. Now, on to the fun stuff: setting up Apache!

Step 4 – Integrate With Apache

It just dawned on me that I completely failed to mention that this needs to be done with Apache 2.2 or higher… but if you’re still on Apache 1… well… I can’t think of anything nice to say. Anyway, we’re going to need to add some stuff to the Apache config, so head on over to the httpd.conf, open it with your favorite text editor, and add the following to the end of the file (it’s easiest to add to the end, and adjust your paths as needed folks):

<directory "/Applications/xampp/xamppfiles/jaxer/aptana">
    Order Deny,Allow
    Deny from all
    Allow from localhost
</directory>
Alias /aptana /Applications/xampp/xamppfiles/jaxer/aptana

<directory "/Applications/xampp/xamppfiles/jaxer/framework">
    Deny from All
    <files clientFramework_compressed.js>
        Allow from localhost
    </files>
</directory>
Alias /jaxer/framework/clientFramework_compressed.js /Applications/xampp/xamppfiles/jaxer/framework/clientFramework_compressed.js

LoadModule jaxer_module "/Applications/xampp/xamppfiles/jaxer/connectors/mod_jaxer.so"
<ifModule jaxer_module>
    DefaultInitEnv "SystemRoot"

    JaxerWorker localManagerWorker localhost 4327
    <location "/jaxer-server">
        SetHandler JAXER
        Order Deny,Allow
        Allow from all
    </location>

    <directory "/Applications/xampp/xamppfiles/jaxer/aptana">
        JaxerFilter localManagerWorker .html
        JaxerFilter localManagerWorker .xhtml
        JaxerFilter localManagerWorker .htm
        JaxerFilter localManagerWorker .php

        Order Deny,Allow
        Deny from all
        Allow from localhost
    </directory>

    <locationMatch "/jaxer-include/">
        JaxerPassThrough
        Order Deny,Allow
        Deny from all
        Allow from localhost
    </locationMatch>
</ifModule>

What we’ve essentially done is told Apache to load the Jaxer module, and then provided some rules for various parts of the Jaxer framework. At this point, you could technically start up Jaxer, but if you want to actually use it in your doc root (/Applications/xampp/xamppfiles/htdocs/ on the Mac), you’ll need to make one more tweak to the httpd.conf file. We need to add the following three lines to the conf file (for me, this was around line 209):

<directory "/Applications/xampp/xamppfiles/htdocs">
    JaxerFilter localManagerWorker .html
    JaxerFilter localManagerWorker .xhtml
    JaxerFilter localManagerWorker .htm
    ...

We do this so all html, xhtml, and html files in our Apache doc root will be filtered through Jaxer, thus allowing us to actually use Jaxer itself inside that directory. Now that all that’s set up, we can start up Jaxer and make sure everything’s running!

Step 5 – Starting Jaxer and Testing

I’ll show you a nice little start / stop script in a moment, but for now let’s just try to fire this puppy up and make sure everything is working properly. First, make sure Apache is stopped (use the XAMPP control panel). Then, bust open a terminal again, and type the following:

cd /Applications/xampp/xamppfiles/jaxer
./JaxerManager --webport=4327 --commandport=4328 --minprocesses=3 --maxprocesses=10 --requesttimeout=60

If everything’s working right, you’ll see the terminal appear to be hanging, with the last line of output being

JaxerManager 0.9.5.2312 (web 4327, command 4328)

That’s good, that means everything is working properly. Right now, Jaxer isn’t logging properly, but that’s OK, we just want to make sure everything is working.
Now that we’ve verified Jaxer will start properly, we can start up Apache (again, use the XAMPP control panel). You shouldn’t see any errors, and if you browse to http://localhost, you should end up at the XAMPP start page:

XAMPP & Jaxer Running Together… So far, so good!

OK, at this point we can do one of two things… We could either create a nice start / stop control script for Jaxer, or we could jump right into testing. I would suggest creating the control script because we can make sure that Jaxer will be logging properly when all is said and done. Right now, it isn’t, because we haven’t set up the proper environment variables for this. If you’re a windows user, you’re in luck, the script is already made for you… just double-click on the “StartJaxer.bat” file in the jaxer folder (inside of XAMPP). If you’re a mac / linux user you *could* technically use the .sh files that come with the stand-alone, but I’ve cooked up something even easier…

Step 6 – The Control Script and Jaxer Tests

OK, so, there’s a small catch with this control script: You have to run it from the command line, and from the jaxer directory. This is mostly because my bash kung-fu isn’t all that strong (if you can make this runnable from anywhere, let me know so I can update this script here). At any rate, the other thing to be aware of is that you must always start Jaxer first, then XAMPP’s Apache. If you ever restart Jaxer, you must also subsequently restart Apache.

OK, let’s get this script written. First, stop the Jaxer we left running by switching back to the terminal window and hitting ctrl+c. Then shut down apache. Create a new text file called “jaxerctl” in the jaxer directory, and paste the following into it:

#!/bin/sh
ARGV="$@"
JAXER_WEBPORT=4327
JAXER_COMMANDPORT=4328
JAXER_MINPROCESSES=3
JAXER_MAXPROCESSES=10
JAXER_REQUESTTIMEOUT=60
JAXER_MANAGER='JaxerManager'

case $ARGV in
start)
    echo Starting Jaxer...
    export JAXER_LOGFILE=file:///Applications/xampp/xamppfiles/logs/jaxer.log
    ./$JAXER_MANAGER --webport=$JAXER_WEBPORT --commandport=$JAXER_COMMANDPORT --minprocesses=$JAXER_MINPROCESSES --maxprocesses=$JAXER_MAXPROCESSES --requesttimeout=$JAXER_REQUESTTIMEOUT > ../logs/jaxer_log.log &
    ERROR=$?
    ;;
stop)
    echo Stopping Jaxer...
    ./tellJaxerManager -p $JAXER_COMMANDPORT stop
    ERROR=$?
    ;;
esac

exit $ERROR

Once you’ve got that saved, you’ll need to make it executable:

sudo chmod 755 jaxerctl

, and then we can start up Jaxer!

./jaxerctl start

That’s it! Now we can get started testing Jaxer, so go ahead and start up Apache again, head over to http://localhost and make sure the XAMPP page pops up. If it does, now we can head over to the Jaxer page: http://localhost/aptana

Remember, we set this up in the httpd.conf file, and all that you see here is provided by Aptana to help you diagnose problems with Jaxer, check out some cool examples, and read up on the documentation. You should see a screen that looks like this:

The Jaxer Server Start Screen

See it? Great, let’s run some tests. Click on the “Server Diagnostics” link to the left. The resulting screen will show you the result of some basic tests that get run to make sure Jaxer is running normally. If all’s well, your screen will look very close to this:

The Jaxer Diagnostics Screen

Wrapping Up and Next Steps

Not so bad, right? You’re all set to start playing around with some of the coolest new technology to hit the web. I really encourage you to do so, as I’m sure you’ll start realizing a lot of the things I have about Jaxer (and I’ll be writing about those soon), but hopefully the most important thing: You’re going to write less code, and it’s going to be cleaner! I’m not going to say how or why right now, but trust me, if you start playing around, you’ll see what I’m talking about.

So, what’s next? Check out the sample apps included with Jaxer (there’s a link on the left-hand side of the Jaxer server start page), or read the Jaxer Book / Documentation. There’s a lot of good stuff in there, and it’s all by the guys that wrote Jaxer. Seriously, this is cool stuff, and it’s so incredibly simple… it took me less than a day to get comfortable with the better part of Jaxer’s functionality and nuances. Coming soon: a Jaxer Photo Gallery (and how it’s more gooder than a plain ‘ol PHP+JavaScript gallery).