Repository files navigation

Attention! This is a master branch supporting Erlang 18. For older Erlang versions use legacy branch.

Chicago Boss is a server framework inspired by Rails and written in Erlang. Itoffers all the conveniences of modern web development, including Comet. What setsChicago Boss apart from other non-Erlang frameworks is that it can handle largeamounts of traffic without any drop in performance. What sets Chicago Boss apartfrom other Erlang frameworks is that it is easy to set up and use.

WARNING: Chicago Boss does not work with Erlang R16B03 due to an error in erl_syntax

After downloading and extracting, type

makemake app PROJECT=mynewprojectcd ../mynewproject./init-dev.sh

For Windows, type

windows-make.batwindows-make.bat app PROJECT=mynewprojectcd ..\mynewprojectstart-server.bat

Then visithttp://localhost:8001/ in your browser. Congratulations, you havea web server. There will be a lot of PROGRESS REPORTs on your console buteverything should be running smoothly.

The project name should be a legal Erlang atom, i.e. start with a lowercaseletter and contain only letters, digits, and underscores (for easy compatibility is recommended name the project dir and app name the same).

• Erlang 19.0 or later -

  http://www.erlang.org/download.html

  • Check witherlang:system_info(otp_release).

• On Windows Vista or Windows 7 -

  • Erlang bin directory must be in PATH.

You probably want to install the CB admin interface. Download it from

<https://github.com/ChicagoBoss/cb_admin>

Uprading used to be a pain but now it is easy. See README_UPGRADE

By default CB uses an in-memory database that needs no configuration. To startworking with an actual database, See README_DATABASE

Why another web framework? Because Rails apps are slow and Node apps are messy.Chicago Boss takes advantage of functional programming and under-the-hoodcompiler magic to provide clean, understandable controller logic, Django-styletemplates, and an ORM based on Erlang's parameterized modules. The best part isthat the network I/O is 100% asynchronous so you can seamlessly integrate Cometendpoints into your app, and you never have to worry about a slow databasequery dragging down unrelated requests.

CB ships with all the tools you need to build a feature-ful website, includingsessions, URL routing, filtering requests and post-processing responses,frameworks for sending and receiving email, JSON generation, Comet vialong-poll and message queues, and internationalization (i18n). Read on fordetails.

Databases. Chicago Boss currently supports MySQL, PostgreSQL, Tokyo Tyrant,Mnesia, MongoDB, and Riak. In CB 0.5.4 and later, you can mix and matchdatabases by configuring Boss to use vertical shards. For SQL databases, theconventions are similar to Rails (plural nouns for the table names, object_idfor foreign keys, etc.).

BossRecords. Boss's take on ActiveRecord is called a BossRecord, which isan Erlang parameterized module on steroids. You instantiate a BossRecord likea regular parameterized module:

Article=article:new('id',"This is a title","This is a body")

But then CB generates functions and attaches them to BossRecords, so you canwrite code like

{ok,SavedArticle}=Article:save()

Before saving to the database, the save() function will call a function calledvalidation_tests(), where you can perform custom validation logic.

CB also generates getter functions which can be invoked directly in templates,so in your template you can write things like

{{article.title }}

Speaking of which...

Templates. Chicago Boss uses ErlyDTL, an Erlang implentation of Django templatelanguage. In fact, Chicago Boss originated with a rewrite of ErlyDTL, and the sameperson maintains both projects so you always get the latest ErlyDTL features. Templatescan access and loop over values stored in proplists, dictionaries, and BossRecords,so you can move data from the database to your templates with a minimum of massaging.

In addition, templates are tightly integrated with Boss's i18n machinery. The admininterface automatically parses templates for translatable strings, and Boss canchoose which language to serve based on the request's Accept-Languages header andthe calculated translation coverage for a particular page. Multi-language websitesare easy to develop with Chicago Boss.

Controllers. Erlang's pattern-matching is a perfect fit for writingcontroller logic. Your controllers are passed the URL method (GET, POST) and a listof URL tokens, and just need to return a tuple telling Boss what to do, for example:

• {ok, Variables} - render the default template with Variables
• {render_other, Variables} - render another template
• {redirect, URL} - redirect the request
• {json, Proplist} - encode the Proplist as JSON and send to the client
• {output, Data} - send Data to the client

If you come from Rails, you'll instantly notice the benefit of Erlang'slanguage design: you don't need an uglycase request.method statement insideevery action, you never have atrocities likerender and return, and you canalways see every variable that is in scope. In CB apps, controller logic isalways concise and usually a pleasure to read.

Sessions. You can configure sessions to be stored in memory (ETS) or in anMnesia database. Theboss_session andboss_flash modules provide functionsfor storing and retrieving session information.

Routes. By default, Chicago Boss uses the same routing conventions as Ruby onRails (/controller/action/id). You can customize the routes and providea base URL in the priv/application.routes file. Of course, most routing occurswith the pattern-matching controller logic, e.g.

posts('GET', ["category",Category])->

You can then generate URLs to match controller patterns in your templates likeso:

{% url action="posts" category="some category" %}

Email. Chicago Boss ships with a miniature MVC for sending multipart emails.Emails can be templated with ErlyDTL, and it is easy to provide plain-text andHTML versions of the same email. In testing environments, email can be sentdirectly to the recipient, or in production can be relayed to an SMTP server.

A Chicago Boss server can also receive email over SMTP. Each email address mapsto a function in your incoming mail controller, so it is easy to writewell-organized email applications. Your email controller has access to theexact same resources as your web controllers, including database requests,BossRecord instantiation, and the message queue; web and email are fullyintegrated.

Comet. It's simple to write a Comet endpoint in Chicago Boss. Unlike anyother language, Erlang gives you the benefits of asynchronous networkcommuncation without using callbacks. Here is a trivial example of a long-pollcontroller:

longpoll('GET', [Channel])->    {ok,Timestamp,Messages}=boss_mq:pull(Channel,last),    {json, [{timestamp,Timestamp}, {messages,Messages}]}.

The call topull blocks until a message is received. Because processes arecheap in Erlang, the overhead of keeping alive a blocking request is very small(just a few kilobytes of memory, compared to megabytes in Rails). You canthus keep alive thousands of Comet request with just a few megabytes of memory.Also notice that the controller logic remains nice and clean (no callbacks). Wecan perform an arbitrary sequence of asynchronous network requests withoutincreasing the scope level.

Events. An interesting feature of Chicago Boss is the events API calledBossNews. With it, you can watch a record or a set of records for changes,then execute a callback when a change is witnessed. Combined with long-polling,you can provide a real-time view of your database on your website. Events canalso be used to provide a clean separation of business logic and notificationlogic.

Tests. Chicago Boss has a kick-ass testing framework. Once you try it youwon't go back. That's all I'll say for now.

Most of Chicago Boss's planned features have been implemented at this point. Ithasn't really been tested in a distributed environment, but it's alreadyrunning on a few public-facing websites, and many more internal websites (or soI am told). It would be nice to add more databases (such as CouchDB and Oracle)and support horizontal sharding. The last main feature before 1.0 will bethe ability to distribute apps written in Chicago Boss as standalone OTPapplications.

See the FAQ and API files located at

http://www.chicagoboss.org/

If you need help getting started, check the new pdf tutorial:

http://www.chicagoboss.org/tutorial.pdf

Be sure to also check the wiki

https://github.com/ChicagoBoss/ChicagoBoss/wiki

There's also the mailing list:

http://groups.google.com/group/chicagoboss

If you want to contribute to CB

CODING_STANDARDS.md

View the CHANGELOG.md

CHANGELOG.md