Motivation
I’ve been working on a project off and on for the past year which uses the Spring Framework extensively. I love Spring for how easy it makes web development, from wiring up various persistence and validation libraries, to dependency injection, and brainless security and model-view-controller functionality. However, as the project has grown, I’ve become more and more frustrated with one aspect of Spring and Java web development in general: performance and resource usage. It’s so bad, I’ve pretty much stopped working on it altogether. Between Eclipse and Tomcat, you’ve already spent over 2 GB of memory, and every time you make a source code change, Tomcat has to reload the application which takes up to 30 seconds on my system, if it doesn’t crash first. This doesn’t suit my development style of making and testing lots of small, incremental changes.
So rather than buy a whole new computer, I’ve started to look for a new lightweight web framework to convert the project to. I really like Erlang and have wanted to write something big in it for a while, so when I found the Nitrogen Web Framework, I thought this might be my opportunity to do so. Erlang is designed for performance and fault-tolerance and has a great standard library in OTP, including a distributed database, mnesia, which should eliminate my need for an object-relational mapper (it stores Erlang terms directly) and enable me to make my application highly available in the future without much fuss. Nitrogen has the added benefit of simplifying some of the fancy things I wanted to do with AJAX but found too difficult with Spring MVC.
The thing I don’t like about Nitrogen is that it is designed to deliver a complete, stand-alone application with a built-in web server of your choosing and a copy of the entire Erlang runtime. This seems to be The Erlang/OTP Way of doing things, but it seems very foreign to me. I already have Erlang installed system-wide and a web server, Yaws, that I have a lot of time invested in. I’d rather use Nitrogen as a library in my application under Yaws just like I was using Spring as a library in my application under Tomcat.
Procedures
I start my new project with Rebar:
$ mkdir test && cd test
$ wget https://bitbucket.org/basho/rebar/downloads/rebar && chmod +x rebar
$ ./rebar create-app appid=test
==> test (create-app)
Writing src/test.app.src
Writing src/test_app.erl
Writing src/test_sup.erl
$ mkdir static include templates
Now I define my project’s dependencies in rebar.config in the same directory:
{deps, [
{nitrogen_core, "2.1.*", {git, "git://github.com/nitrogen/nitrogen_core.git", "HEAD"}},
{nprocreg, "0.2.*", {git, "git://github.com/nitrogen/nprocreg.git", "HEAD"}},
{simple_bridge, "1.2.*", {git, "git://github.com/nitrogen/simple_bridge.git", "HEAD"}},
{sync, "0.1.*", {git, "git://github.com/rklophaus/sync.git", "HEAD"}}
]}.
These dependencies are taken from Nitrogen’s rebar.config. Next I write a Makefile to simplify common tasks:
default: compile static/nitrogen
get-deps:
./rebar get-deps
include/basedir.hrl:
echo '-define(BASEDIR, "$(PWD)").' > include/basedir.hrl
static/nitrogen:
ln -sf ../deps/nitrogen_core/www static/nitrogen
compile: include/basedir.hrl get-deps
./rebar compile
clean:
-rm -f static/nitrogen include/basedir.hrl
./rebar delete-deps
./rebar clean
distclean: clean
-rm -rf deps ebin
I expect I’ll be tweaking this Makefile some more in the future, but it demonstrates the absolute minimum to compile the application. When I run make, four things happen the first time:
- BASEDIR is defined as the current directory in include/basedir.hrl. We’ll use this later.
- All of the Nitrogen dependencies are pulled from Git to the deps directory.
- All of the code is compiled.
- The static content from Nitrogen (mostly Javascript files) is symlinked into our static content directory.
Next I prepare the code for running under Yaws. First I create the Nitrogen appmod in src/test_yaws.erl:
-module(test_yaws).
-export ([out/1]).
out(Arg) ->
RequestBridge = simple_bridge:make_request(yaws_request_bridge, Arg),
ResponseBridge = simple_bridge:make_response(yaws_response_bridge, Arg),
nitrogen:init_request(RequestBridge, ResponseBridge),
nitrogen:run().
This is taken from Nitrogen repository. I also modify the init/0 function in src/test_sup.erl to start the nprocreg application, similar to how it is done in Nitrogen proper:
init([]) ->
application:start(nprocreg),
{ok, { {one_for_one, 5, 10}, []} }.
Lastly, I add a function to src/test_app.erl which can be used by Yaws to start the application:
-export([start/0]).
start() ->
application:start(test).
One other thing that I do before loading the application up in Yaws is create a sample page, src/index.erl. This is downloaded from Nitrogen:
-module (index).
-compile(export_all).
-include_lib("nitrogen_core/include/wf.hrl").
-include("basedir.hrl").
main() -> #template { file=?BASEDIR ++ "/templates/bare.html" }.
title() -> "Welcome to Nitrogen".
body() ->
#container_12 { body=[
#grid_8 { alpha=true, prefix=2, suffix=2, omega=true, body=inner_body() }
]}.
inner_body() ->
[
#h1 { text="Welcome to Nitrogen" },
#p{},
"
If you can see this page, then your Nitrogen server is up and
running. Click the button below to test postbacks.
",
#p{},
#button { id=button, text="Click me!", postback=click },
#p{},
"
Run <b>./bin/dev help</b> to see some useful developer commands.
"
].
event(click) ->
wf:replace(button, #panel {
body="You clicked the button!",
actions=#effect { effect=highlight }
}).
I make sure to include basedir.hrl (generated by the Makefile, remember?) and modify the template path to start with ?BASEDIR. Since where Yaws is running is out of our control, we must reference files by absolute pathnames. Speaking of templates, I downloaded mine from the Nitrogen repository. Obviously, it can be modified however you want or you could create one from scratch.
Before we continue, I recompile everything by typing make.
Now the fun begins: wiring it all up in Yaws. I use my package for OpenSolaris which puts the configuration file in /etc/yaws/yaws.conf. I add the following to it:
ebin_dir = /docs/test/deps/nitrogen_core/ebin
ebin_dir = /docs/test/deps/nprocreg/ebin
ebin_dir = /docs/test/deps/simple_bridge/ebin
ebin_dir = /docs/test/deps/sync/ebin
ebin_dir = /docs/test/ebin
runmod = test_app
<server test.thestaticvoid.com>
port = 80
listen = 0.0.0.0
docroot = /docs/test/static
appmods = </, test_yaws>
</server>
Obviously, your paths will probably be different. The point is to tell Yaws where all of the compiled code is, tell it to start your application (where the business logic will be contained), and tell it to use the Nitrogen appmod. Restart Yaws and it should all be working!
Now for some cool stuff. If you run the svc:/network/http:yaws service from my package, or you start Yaws like yaws --run_erl svc, you can run yaws --to_erl svc (easiest to do with root privileges) and get access to Yaws’s Erlang console. From here you can hot-reload code. For example, modify the title in index.erl and recompile by running make. In the Erlang console, you can run l(index). and it will pick up your changes. But there is something even cooler. From the Erlang console, type sync:go(). and now whenever you make a change to a loaded module’s source code, it will automatically be recompiled and loaded, almost instantly! It looks something like:
# yaws --to_erl svc
Attaching to /var//run/yaws/pipe/svc/erlang.pipe.1 (^D to exit)
1> sync:go().
Starting Sync (Automatic Code Reloader)
ok
2>
=INFO REPORT==== 17-Feb-2011::15:03:10 ===
/docs/test/src/index.erl:0: Recompiled. (Reason: Source modified.)
=INFO REPORT==== 17-Feb-2011::15:04:20 ===
/docs/test/src/index.erl:11: Error: syntax error before: body
=INFO REPORT==== 17-Feb-2011::15:04:26 ===
/docs/test/src/index.erl:0: Fixed!
2> sync:stop().
=INFO REPORT==== 17-Feb-2011::15:07:17 ===
application: sync
exited: stopped
type: temporary
ok
One gotcha that may or may not apply to you, is that Yaws should have permission to write to your application’s ebin directory if you want to save the automatically compiled code. In my case, Yaws runs as a different user than I develop as, a practice that I would highly recommend. So I use a ZFS ACL to allow the web server user read and write access:
$ /usr/bin/chmod -R A+user:webservd:rw:f:allow /docs/test/ebin
$ /usr/bin/ls -dv /docs/test/ebin
drwxr-xr-x+ 2 jlee staff 8 Feb 17 15:04 /docs/test/ebin
0:user:webservd:read_data/write_data:file_inherit:allow
1:owner@::deny
2:owner@:list_directory/read_data/add_file/write_data/add_subdirectory
/append_data/write_xattr/execute/write_attributes/write_acl
/write_owner:allow
3:group@:add_file/write_data/add_subdirectory/append_data:deny
4:group@:list_directory/read_data/execute:allow
5:everyone@:add_file/write_data/add_subdirectory/append_data/write_xattr
/write_attributes/write_acl/write_owner:deny
6:everyone@:list_directory/read_data/read_xattr/execute/read_attributes
/read_acl/synchronize:allow
ACLs are pretty scary to some people, but I love ‘em 
Other Thoughts
You would not be able to run multiple Nitrogen projects on separate virtual hosts using this scheme. Nitrogen maps request paths to module names (for example, requesting “/admin/login” would load a module admin_login) and module names must be unique in Erlang. I think it would be possible to work around this using a Yaws rewrite module, though I haven’t tested it. I imagine if one virtual host maps “/admin/login” to “/foo/admin/login” and another maps it to “/bar/admin/login”, then Nitrogen would search for foo_admin_login and bar_admin_login, respectively, eliminating the conflicting namespace problem.
Now that I’ve gone through all the trouble of setting up Nitrogen the way I like, I should start converting my application over. Hopefully I’ll like it. It would be a shame to have done all this work for naught. I’m sure there will be posts to follow.
I am a Unix sysadmin and grad student at