Prax¶ ↑

A pure ruby alternative to Pow!!

Aka a Rack application spawner and proxy for simpler local development. Calling myapp.dev and subdomain.myapp.dev with no configuration is simpler than editing your hosts file, starting your applications manually on port 3000, etc.

NOTE: a full rewrite of Prax is available in the unstable branch and comes with a few more features than available in the current master branch. You are encouraged to try it out —it may be more compatible with the different Ruby version managers, and has an autokill monitor to kill the apps after a TLL, among other things.

Why a pure-ruby alternative?¶ ↑

My GNU/Linux fork of Pow just broke on me badly, and I couldn’t read, less write the coffeescript it’s written in. I thus decided to try writing an alternative in Ruby. Good for me, because I now have a viable alternative, and learned a lot about TCP and UNIX sockets, the HTTP protocol, Rack and Ruby Threads.

Also, Prax only requires Ruby and the Rack gem, both you should have already installed if you are a Ruby Web developer.

Rubies¶ ↑

Prax has been developed with MRI Ruby 1.9.3, but should be compatible with most ruby engines. It has been tested on:

- Ruby 1.8.7
- Ruby 1.9.3
- Rubinius 2.0.0 (HEAD)
- JRuby 1.7.0 (1.9 mode)

Please note that Ruby 1.8.7 and Rubinius in 1.8 mode also require the sfl (spawn for legacy) gem, because Ruby 1.8 doesn’t support Process.spawn which was introduced in Ruby 1.9. If you’re using Bundler, add it to your Gemfile.

Jruby in 1.8 mode isn’t supported, because sfl requires fork which isn’t available on all platforms (not even GNU/Linux). Also, Jruby 1.6.8 just doesn’t work with Prax, neither in 1.8 nor 1.9 modes.

Installing on GNU/Linux¶ ↑

First clone the repository (it’s suggested you put it somewhere like /opt), and run the installer which will install the port forwarding script and NSSwitch extension.

$ sudo git clone git://github.com/ysbaddaden/prax.git /opt/prax

$ cd /opt/prax/
$ ./bin/prax install

And you’re done! You only need to link your apps by going to your rails root path and calling link:

$ cd ~/Work/myapp
$ prax link

If you want the prax server to automatically start, simply add the following to your .bash_profile or .profile:

prax start

Or install manually (from cloned prax directory):

$ sudo ln -s bin/prax /usr/local/bin/prax
$ sudo cp install/initd /etc/init.d/prax
$ sudo chmod +x /etc/init.d/prax
$ sudo update-rc.d prax defaults

$ cd ext/
$ make
$ sudo make install

Edit /etc/nsswitch.conf and add prax to the hosts line, then restart your browser, otherwise it won’t use the newly configured prax resolver.

Create the ~/.prax directory and link your apps to it. You may link the same folder multiple times as different names to serve it from different domains.

$ mkdir ~/.prax
$ ln -sf ~/Work/myapp ~/.prax/

$ sudo /etc/init.d/prax start
$ prax start

Point your browser to http://myapp.dev/ and wait for your Rack app to spawn.

HTTPS¶ ↑

To start an HTTPS server, you need to have an SSL certificate file and an RSA/DSA key file.

The key file and a self-signed certificate can be genterated automatically by running the generate.rb script. Since this certificate is only being used for local development, you can just accept the defaults for all the prompts.

$ cd /opt/prax/ssl; bash ./generate.sh

Optionally you can use your own certificate by copying the file to:

$ cp <path_to_crt_file> /opt/prax/ssl/server.crt
$ cp <path_to_key_file> /opt/prax/ssl/server.key

If you also require an intermediate or bundle certificate file, you can add that too:

$ cp <path_to_bundle_file> /opt/prax/ssl/ca.pem

Next (re)start prax:

$ prax start

**This will result in a security warning because the browser cannot validate it against a local, trusted issuer certificate.** For development, this should not be of much concert and you can add an exception for this in your browser.

Now you can point your browser to https://myapp.dev/ and test the app via SSL.

Custom Configuration¶ ↑

You can modify the default behavior by creating a ~/.praxconfig file.

These are the defaults:

PRAX_ROOT=/opt/prax/libexec
PRAX_HOSTS=~/.prax
PRAX_DEBUG=false

Known bug¶ ↑

The NSSwitch extension may cause some instability in the software stack, like a crashing browser, or some software not resolving domains anymore. You may want to reconfigure the NSSswitch by moving the prax NSSwitch extension after the dns one, so it looks like this (in /etc/nsswitch.conf):

hosts: files mdns4_minimal [NOTFOUND=return] dns prax mdns4

Which should solve the problem, but might cause prax itself to resolve .dev domains with a regular delay (around 5 seconds).

Mac OS X¶ ↑

Mac OS X isn’t supported yet. Feel free to contribute!

Features¶ ↑

This is a work in progress, and Prax is missing some features to be on par with Pow. Mostly on the configuration side of your development machine. Yet it’s already capable to start the HTTP server, spawn your apps, proxy requests, and more.

• HTTP Server

• HTTP Proxy

• Rack Handler (Racker)

• Rack Application spawn / restart / always restart

• SSL support (if certs and keys are generated)

• xip.io support

• GNU/Linux:

  • NSSwitch DNS resolver (resolves *.dev domains to 127.0.0.1)

  • firewall rule (redirects root ports 80/443 to user ports 20559/20558)

  • install script

TODO¶ ↑

• commands for the prax script:

  • prax always_restart

• Mac OS X:

  • firewall rule

  • DNS resolver

  • install script

Credits¶ ↑

• Julien Portalier <[email protected]>

• Sam Stephenson, Nick Quaranto, 37signals for the sub comamnd

• pyromaniac for the initial NSSwitch extension