Upgrading to Nitrogen 2.3

Home | Getting Started | API | Elements | Actions | Validators | Handlers | Configuration Options | Plugins | Mobile | Troubleshooting | About

Upgrading to Nitrogen 2.3

Table of Contents

1 Overview

Upgrading to Nitrogen 2.3 is simple, however, ensuring that your upgraded app supports Websockets will require a small amount of work (mostly copying a few files, and checking simple configurations).

The Simple Method (which won't allow the use of Websockets)

Nitrogen 2.3 is designed to be completely backwards compatible with Nitrogen 2.2 and earlier, meaning no changes to your existing codebase should be required (beyond recompiling your modules to support any changes to header files).

If downtime is acceptable, you can do the following after bringing down your Erlang VM.

To upgrade to Nitrogen 2.3, you'll want to update your rebar.config and change the nitrogen_core appliation to use the "v2.3.0" tag, and update the simple_bridge application to use the "v2.0.0" tag:

{nitrogen_core, "", {git, "git://github.com/nitrogen/nitrogen_core", {tag, "v2.3.0"}}},
{simple_bridge, "", {git, "git://github.com/nitrogen/simple_bridge", {tag, "v2.0.0"}}},

Then run make upgrade in your app, which should fetch the latest versions and recompile your app accordingly.

Your application will then be upgraded.

Upgrading with Sync

If you wanted, you can enable sync, either with bin/dev compile (at the *nix terminal) or with sync:go() (at the Erlang Shell).

Then run the above instructions for upgrading. Depending on the size of your application, you may experience a little bit of downtime while your Nitrogen installation is recompiling, but as soon as its finished, Sync will load the modules and you'll be good to go.

The Simple Method with Sync and without any Downtime

If you want to ensure you don't experience any downtime during this upgrade, you're going to want to upgrade your sync version first.

The easiest way to do this is to first start sync in your Nitrogen application, either with sync:go() or at the Linux/Unix terminal with bin/dev compile.

Then we're going to manually upgrade sync:

$ cd lib/sync
$ git checkout master
$ git pull origin master

That second line is just to make sure we're actually on the master branch. Previous versions of Nitrogen had an issue that might have caused us to be on a detached branch, this will ensure we're good to go.

After running that command, sync very likely would have crashed. That's okay: it's supervised, so it would be restarted with a fresh state.

Now that sync is upgraded, we're going to want to pause it:

At the Erlang console, run:

> sync:pause().

Now let's unpause sync:

> sync:unpause().

This should start a whole slew of things going on in the erlang VM, scrolling really fast (just notifying you of updated BEAM files), and when it's finished, your application will be upgraded and live with no downtime.

The More Complete Method

The previous instructions were okay as long as you don't care about Websockets.

If you want to use websockets, however, it's going to take a little bit more work.

Please note that these instructions will require a bit of downtime because we'll have to take the underlying server offline to be restarted by SimpleBridge. In this case, we may as well stop sync before doing this process.

Same as above, we're going to need to add the same rebar dependencies:

{nitrogen_core, "", {git, "git://github.com/nitrogen/nitrogen_core", {tag, "v2.3.0"}}},
{simple_bridge, "", {git, "git://github.com/nitrogen/simple_bridge", {tag, "v2.0.0"}}},

Then run make upgrade.

Now we're going to need to download a few files. Feel free to copy and paste the following into your *nix shell:

$ curl https://raw.githubusercontent.com/nitrogen/nitrogen/master/rel/overlay/common/site/src/nitrogen_main_handler.erl -o site/src/nitrogen_main_handler.erl
$ curl https://raw.githubusercontent.com/nitrogen/nitrogen/master/rel/overlay/common/site/src/nitrogen_sup.erl -o site/src/nitrogen_sup.erl
$ curl https://raw.githubusercontent.com/nitrogen/nitrogen/master/rel/overlay/common/etc/simple_bridge.config -o etc/simple_bridge.config

Notice that the second line will actually overwrite the current nitrogen_sup.erl file, so if you have anything customized there, make note of it or make a backup first.

Now you'll want to copy any custom handlers and other configs you've manually added to site/src/nitrogen_PLATFORM.erl into site/src/nitrogen_main_handler.erl before into the handlers() function. This will ensure that your custom handlers get initialized with both standard requests and websocket requests.

So if your nitrogen_mochiweb.erl file looked like this:

-export ([loop/1]).

loop(Req) ->
    {ok, DocRoot} = application:get_env(mochiweb, document_root),
    RequestBridge = simple_bridge:make_request(mochiweb_request_bridge, {Req, DocRoot}),
    ResponseBridge = simple_bridge:make_response(mochiweb_response_bridge, {Req, DocRoot}),
    nitrogen:init_request(RequestBridge, ResponseBridge),
    wf:content_type("text/html; charset=utf-8"),
    nitrogen:handler(myapp_route_handler, []),

Then we're going to want our nitrogen_main_handler.erl file to look like this:


   handlers() ->
       nitrogen:handler(myapp_route_handler, []),

   ws_init() ->

   run() ->
       wf:content_type("text/html; charset=utf-8"),

You'll notice above that we don't set the header or content type in the ws_init() function. This is because the headers would have already been sent when the websocket connection is established.

Next, we're going to edit etc/simple_bridge.config to make sure we're binding to the correct IP address and ports and that those settings are all correct (static paths, max post post and file sizes, etc).

At this point, we can safely remove your site/PLATFORM.config file and your old site/src/nitrogen_PLATFORM.erl file (where PLATFORM is your server of choice).

From here, you can run a simple make upgrade, and your application will be upgraded.

Go ahead and kill the Erlang VM and restart it and it should be good to go, complete with websocket support.

A Note about Nginx and Reverse Proxies

If you are using Nginx as a reverse proxy for Nitrogen, and if you wish to support Websockets, you're going to need to be running at least version 1.4 of Nginx.

Date: 2015-01-29 17:28:06 CST

Author: Jesse Gumm (@jessegumm)

Org version 7.8.02 with Emacs version 23

Validate XHTML 1.0


Note:To specify code blocks, just use the generic code block syntax:
<pre><code>your code here</code></pre>

comments powered by Disqus