Persevere is not a single monolithic web server like Apache. Rather, it’s a set of server apps – or JSGI middleware – working together. While this is very powerful in terms of flexibility and extensibility, it complicates the installation process. Installing Persevere has become much easier with tools such as Nodules, however, the whole process might still not be for the faint-hearted.
Deciding on a server engine
The first decision you have to make is which server engine to base your Persevere instance on. Two options exist:
node.js is a JavaScript-interpreter written in C/C++, which makes is very fast and light-weight. It is based on Google’s V8 JS-engine, which also powers the Chrome web browser. node.js has a completely new take on concurrency. There are virtually no synchronous (blocking) operations – everything is asynchronous – which makes it excel at concurrency, i.e. providing a very good foundation for a web server.
Rhino is a JavaScript-interpreter written in Java. While it is usually second to node.js in terms of performance, it has been around for a longer time. Rhino’s codebase is well tested, stable and much less likely to undergo larger structural changes compared to node.js. Rhino is sponsored by Mozilla and is easier to install since there are official binaries. Narwhal brings a CommonJS module/package system to Rhino. Theoretically Narwhal could be run on any JS-interpreter (including Node.js!), but support for Rhino is the most complete.
Even though Persevere aims to be completely compatible with both node.js and narwhal/rhino, my impression is that it generally works best (fewer issues to troubleshoot) with node.js. This article will assume a node.js server engine.
Installing node.js
You can download the source code from nodejs.org and compile it yourself.
If you have a Mac, you can do it the easy way, by installing a pre-built binary package:
http://sites.google.com/site/nodejsmacosx/
If you’re on Windows, you can compile it using Cygwin. As of quite recently, node.js offers binaries, but only for the unstable (development) versions.
Node.js should now be installed. You can verify this by opening a Terminal and run
node --versionDownload nodules
Like stated above, Persevere consists of many individual components, which may in turn require many other dependencies. To avoid having to fetch them all manually, we use a sub-project of Persevere called nodules, which will automatically download all dependencies for us – on demand.
In fact, nodules also offers a remarkable feature – module hot-reloading. If you’re from a Java-background, you will immediately realize the benefits, but it might not be obvious if you’re from a PHP background (or any other interpreted platform). However, this greatly increases your efficiency when working with Persevere as it will auto-reload your source code when you save your files.
Download nodules from http://github.com/kriszyp/nodules – or use this direct link
Unzip and save nodules in an easily accessible location – nothing needs to be installed.
Installing the Persevere application template
Download persevere-template from github for a bare-bone minimal Persevere application. The template is essentially empty, apart from the minimum amount of code needed to fire up a Persevere server instance.
http://github.com/kriszyp/persevere-template – or use this direct link
Now, using the Terminal, go to the template directory and start the Persevere template app.
cd <path-to-persevere-template> node <path-to-nodules>/lib/nodules.js
You will see that nodules immediately starts to pull in all the required dependencies. The first time you do this, it might take a while, but don’t worry – all modules are cached (saved) in in your app’s subdirectory ”downloaded-modules”.
Did it work?
If there were no errors, you have your very own Persevere app up and running. Verify this by pointing your browser to http://localhost:8080/. It should look something like this:
Persevere being a very dynamic project, odds are that it didn’t work off the bat. If that’s the case, it is most likely due to incompatible dependencies. The file used by nodules to determine which dependencies your Persevere app needs (and where to find them) is called package.json. You find this file in <path-to-persevere-template>/package.json.
Last time I tried (2011-06-10), I had to change versions for perstore and pintura to ”master”, for it to work. Note that changing to ”master” is risky – as this is the development trunk version. If you find a combination of numeric version that work together, you’d better stick with them as their code base won’t change.
{ "name": "", "author": "", "dependencies": ["persevere"], "contributors": [], "mappings":{ "perstore": "http://github.com/kriszyp/perstore/zipball/master", "commonjs-utils": "http://github.com/kriszyp/commonjs-utils/zipball/v0.2.2", "pintura": "http://github.com/kriszyp/pintura/zipball/master", "promised-io": "http://github.com/kriszyp/promised-io/zipball/v0.2.2", "templify": "http://github.com/dmachi/templify/zipball/master", "patr": "http://github.com/kriszyp/patr/zipball/v0.2.2", "rql": "http://github.com/kriszyp/rql/zipball/v0.2.2", "persevere-client": "jar:http://github.com/kriszyp/persevere/zipball/master!/public/", "wiky": "http://github.com/kriskowal/wiky/zipball/master", "narwhal": "http://github.com/kriszyp/narwhal/zipball/master", "jack": "jar:http://github.com/kriszyp/jack/zipball/master!/lib/jack/", "transporter": "http://github.com/kriszyp/transporter/zipball/v0.2.2", "jsgi-node": "jar:http://github.com/kriszyp/jsgi-node/zipball/v0.2.2!/lib/jsgi-node.js", "multi-node": "http://github.com/kriszyp/multi-node/zipball/v0.2.2", "tunguska": "http://github.com/kriszyp/tunguska/zipball/v0.2.2" } }
