jgordor edited this page Jan 29, 2012 · 5 revisions

Upgrade: From 0.6 to 0.7

Not relesed yet, clone master git://github.com/evanmiller/ChicagoBoss.git

In Chicago Boss 0.7, projects are now rebarified, boss.config is the central place for all configuration and eunit testing has been made easy,

./rebar boss # (list of available commands)
./init.sh # (list of available boot commands)

Migrate current cb apps

In order to ease the task, a new make task has been created in the framework Makefile, just update your Chicago Boss and run:

make rebarize APPDIR=/path/to/app

This will copy all new files in your app directory, move the app.src file to src, move the boss_web_tests (functionals) to src/test/functional and point you with instructions on what you need add to your boss.config.

make rebarize APPDIR=../my_app
../my_app rebar-boss-ified
WARNING: your boss.config have not been changed, you need to set:
- in boss app section:
---- {path, "/path/to/chicago_boss"}
---- {vm_cookie, "my_secret_cookie"} % Optional, defaults to abc123
- for each app defined:
---- {path, "../path/to/app"}
INFO: you can safely remove the Makefile and start* files from your app dir
INFO: after the boss.config change, you can run:
cd ../my_app
./rebar boss # Shows all boss-rebar commands
./init.sh # Shows the new boot system commands


Boss has non-standard-compatible-rebar-way of compiling code, the rebar plugin switches off standard compilation and calls the boss_load module.

./rebar compile (works for compatibility mode)
./rebar boss c=compile


Now the only file on a cb project you need to take care is boss.config, the new init.sh calls ./rebar boss commands that returns automatically generated erl -pa… commands and executes it.

You now defines the path in boss.config for each app and (compilation, test launch, start, stop, reload, …) works automatically.

A new setting in boss.config called vm_cookie (optional) has been added, used in start/stop/reload commands (defaults to “abc123”):

[{boss, [ {path, "../ChicagoBoss"}, {vm_cookie, "abc123"}, ...


Eunit testing compilation/setup works automatically, start writing unit tests, just place them in “src/test/eunit” and run ./rebar eunit or ./rebar boss c=test_eunit

Functional tests lives now in src/test/functional (before was placed in src/test), just call ./rebar boss c=test_functional


The init.sh handles start, start-dev as before, but also stop, reload (hot for the node) and restart is implemented.

Now we can tweak, change, make vm.args configurable (in boss.config) without force developers to handle this manually in their apps.

Upgrade: From 0.5 to 0.6

Starting with Chicago Boss 0.6, projects follow an OTP layout, and the admin interface is a standalone OTP application.

To upgrade, you will need to do the following in your project:

mkdir src
mkdir priv
mv controller/ init/ lib/ mail/ model/ test/ view/ src/
mv lang/ static/ priv/
PROJECT=my_application mv boss.routes priv/$PROJECT.routes

In addition, you will need to prefix your controller modules with the application name. E.g.
mv blog_controller.erl my_application_blog_controller.erl

This avoids module naming conflicts when multiple applications are installed on the same server (which was not possible prior to 0.6).

Upgrade the framework: Chicago Boss 0.5 and later

Starting with Chicago Boss 0.5, your project is kept separate from the Chicago Boss source code. The project files “start.sh” and “start-dev.sh” contain references to the CB ebin/ directory. After downloading a new version of CB, simply type “make” to build it, and then update your “start.sh” and “start-dev.sh” files according to point to the new CB version, if it’s in a new directory.

However, the /admin interface is considered part of your project (this will probably change in the future). If you want to take advantage of new features in the /admin interface, you need to replace your project’s “admin” directory with the “skel/admin” directory from the CB source.

Upgrade the framework: Chicago Boss 0.4 to 0.5

The easiest way to upgrade to 0.5 is to create a new project and copy your project code over. In the ChicagoBoss-0.5.x directory, type

make app PROJECT=mynewproject
cd ../mynewproject

The new project structure should look like this:

emiller blackstone ~/src/mynewproject $ ls -l
total 208
-rw-r--r--  Makefile
drwxr-xr-x  admin
-rw-r--r--  boss.config
drwxr-xr-x  controller
drwxr-xr-x  ebin
drwxr-xr-x  lang
drwxr-xr-x  lib
drwxr-xr-x  log
drwxr-xr-x  mail
drwxr-xr-x  model
-rwxr-xr-x  start-dev.sh
-rw-r--r--  start-server.bat
-rwxr-xr-x  start.sh
drwxr-xr-x  static
drwxr-xr-x  test
drwxr-xr-x  view

You are now ready to copy over your old project files. Because the only project files that matter begin with lower-case letters, this is as simple as:

cp -a /path/to/old/ChicagoBoss/[a-z]* /path/to/new/mynewproject

You should now be ready to go. Type “./start-dev.sh” in the new project directory and test out your server!

  1. Hot-upgrades in production
    Chicago Boss 0.5 features hot-upgrades of framework and project code in production. To upgrade your project code:
  1. Type “make” in your project directory to compile your project
  2. Copy the ebin/*.beam files over to the project ebin/ directory of your production server
  3. Visit /admin/upgrade on the production server
  4. Click the button that says “Upgrade BEAM Code”

That’s it, you’re done. There should be no downtime or lost requests of any kind.