Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP
Newer
Older
100644 201 lines (142 sloc) 8.269 kB
7bfef2b @evanmiller Update README
evanmiller authored
1 Chicago Boss: Build Something Big
dc3c799 @evanmiller Mail framework; Test docs; Project restructuring
evanmiller authored
2 =================================
d39a1b7 Initial commit of Chicago Boss.
Evan Miller authored
3
7bfef2b @evanmiller Update README
evanmiller authored
4 Chicago Boss is a server framework inspired by Rails and written in Erlang. It
5 offers all the conveniences of modern web development, including Comet. What sets
6 Chicago Boss apart from other non-Erlang frameworks is that it can handle large
7 amounts of traffic without any drop in performance. What sets Chicago Boss apart
9f24895 README update
Evan Miller authored
8 from other Erlang frameworks is that it is easy to set up and use.
7bfef2b @evanmiller Update README
evanmiller authored
9
10
11 60-second Quickstart
12 --------------------
13
14 After downloading and extracting, type
92aa322 @evanmiller Documentation for the config file
evanmiller authored
15
74bd246 @evanmiller Update README for new build system
evanmiller authored
16 make
17 make app PROJECT=mynewproject
18 cd ../mynewproject
19 ./start-dev.sh
20
7bfef2b @evanmiller Update README
evanmiller authored
21 Then visit http://localhost:8001/ in your browser. Congratulations, you have
22 a web server. There will be a lot of PROGRESS REPORTs on your console but
23 everything should be running smoothly.
74bd246 @evanmiller Update README for new build system
evanmiller authored
24
25
26 Dependencies
27 ------------
d39a1b7 Initial commit of Chicago Boss.
Evan Miller authored
28
d6347a0 @evanmiller Prep docs for 0.3.6
evanmiller authored
29 * Erlang R13A or later -
dc3c799 @evanmiller Mail framework; Test docs; Project restructuring
evanmiller authored
30
7ac0ac5 @evanmiller Linkify URLs in README
evanmiller authored
31 <http://www.erlang.org/download.html>
d39a1b7 Initial commit of Chicago Boss.
Evan Miller authored
32
d6347a0 @evanmiller Prep docs for 0.3.6
evanmiller authored
33 * Check with `erlang:system_info(otp_release)`.
c53ee94 Update Medici, serve static files.
Evan Miller authored
34
788d56f Add Medici code to the repository, update Makefiles.
Evan Miller authored
35
02061c5 @strobe
strobe authored
36 * On Windows Vista or Windows 7 -
37
38 1. you need install win openSSl (http://www.slproweb.com/products/Win32OpenSSL.html)
39 2. make mochiweb with msys or cygwin
40
d39a1b7 Initial commit of Chicago Boss.
Evan Miller authored
41
74bd246 @evanmiller Update README for new build system
evanmiller authored
42 Upgrades
43 --------
44
7bfef2b @evanmiller Update README
evanmiller authored
45 Uprading used to be a pain but now it is easy. See README_UPGRADE
74bd246 @evanmiller Update README for new build system
evanmiller authored
46
47
48 Database Setup
49 --------------
d39a1b7 Initial commit of Chicago Boss.
Evan Miller authored
50
7bfef2b @evanmiller Update README
evanmiller authored
51 By default CB uses an in-memory database that needs no configuration. To start
52 working with an actual database, See README_DATABASE
92aa322 @evanmiller Documentation for the config file
evanmiller authored
53
54
9f24895 README update
Evan Miller authored
55 Philosophy and Features
74bd246 @evanmiller Update README for new build system
evanmiller authored
56 -----------------------
92aa322 @evanmiller Documentation for the config file
evanmiller authored
57
9f24895 README update
Evan Miller authored
58 Why another web framework? Because Rails apps are slow and Node apps are messy.
59 Chicago Boss takes advantage of functional programming and under-the-hood
60 compiler magic to provide clean, understandable controller logic, Django-style
61 templates, and an ORM based on Erlang's parameterized modules. The best part is
62 that the network I/O is 100% asynchronous so you can seamlessly integrate Comet
63 endpoints into your app, and you never have to worry about a slow database
64 query slowing down unrelated requests.
65
66 CB ships with all the tools you need to build a feature-ful website, including
67 sessions, URL routing, filtering requests and post-processing responses,
68 frameworks for sending and receiving email, JSON generation, Comet via
69 long-poll and message queues, and internationalization (i18n). Read on for
70 details.
71
72 *Databases*. Chicago Boss currently supports MySQL, PostgreSQL, Tokyo Tyrant,
73 Mnesia, MongoDB, and Riak. In CB 0.5.4 and later, You can mix and match
74 databases by configuring Boss to use vertical shards. For SQL databases, the
75 conventions are similar to Rails (plural nouns for the table names, object_id
76 for foreign keys, etc.).
77
78 *BossRecords*. Boss's take on ActiveRecord is called a BossRecord, which is
79 an Erlang parameterized module on steroids. You instantiate a BossRecord like
80 a regular parameterized module:
81
82 Article = article:new('id', "This is a title", "This is a body")
83
84 But then CB generates functions and attaches them to BossRecords, so you can
85 write code like
86
87 {ok, SavedArticle} = Article:save()
88
89 Before saving to the database, the save() function will call a function called
90 validation_tests(), where you can perform custom validation logic.
91
92 CB also generates getter functions which can be invoked directly in templates,
93 so in your template you can write things like
94
95 {{ article.title }}
96
97 Speaking of which...
98
99 *Templates*. Chicago Boss uses ErlyDTL, an Erlang implentation of Django template
100 language. In fact, Chicago Boss originated with a rewrite of ErlyDTL, and the same
101 person maintains both projects so you always get the latest ErlyDTL features. Templates
102 can access and loop over values stored in proplists, dictionaries, and BossRecords,
103 so you can move data from the database to your templates with a minimum of massaging.
104
105 In addition, templates are tightly integrated with Boss's i18n machinery. The admin
106 interface automatically parses templates for translatable strings, and Boss can
107 choose which language to serve based on the request's Accept-Languages header and
108 the calculated translation coverage for a particular page. Multi-language websites
109 are easy to develop with Chicago Boss.
110
111 *Controllers*. Erlang's pattern-matching is a perfect fit for writing
112 controller logic. Your controllers are passed the URL method (GET, POST) and a list
113 of URL tokens, and just need to return a tuple telling Boss what to do, for example:
114
115 * `{ok, Variables}` - render the default template with Variables
116 * `{render_other, Variables}` - render another template
117 * `{redirect, URL}` - redirect the request
118 * `{json, Proplist}` - encode the Proplist as JSON and send to the client
119 * `{output, Data}` - send Data to the client
120
121 If you come from Rails, you'll instantly notice the benefit of Erlang's
122 language design: you don't need an ugly `case request.method` statement inside
123 every action, you never have atrocities like `render and return`, and you can
124 always see every variable that is in scope. In CB apps, controller logic is
125 alwas concise and usually a pleasure to read.
126
127 *Sessions*. You can configure sessions to be stored in memory (ETS) or in an
128 Mnesia database. The `boss_session` and `boss_flash` modules provide functions
129 for storing and retrieving session information.
130
131 *Routes*. By default, Chicago Boss uses the same routing conventions as Ruby on
132 Rails (`/controller/action/id`). You can customize the routes and provide
133 a base URL in the routes.config file.
134
135 *Email*. Chicago Boss ships with a miniature MVC for sending multipart emails.
136 Emails can be templated with ErlyDTL, and it is easy to provide plain-text and
137 HTML versions of the same email. In testing environments, email can be sent
138 directly to the recipient, or in prouction can be relayed to an SMTP server.
139
140 A Chicago Boss server can also receive email over SMTP. Each email address maps
141 to a function in your incoming mail controller, so it is easy to write
142 well-organized email applications. Your email controller has access to the
143 exact same resources as your web controllers, including database requests,
144 BossRecord instantiation, and the message queue; web and email are fully
145 integrated.
146
147 *Comet*. It's simple to write a Comet endpoint in Chicago Boss. Unlike any
148 other language, Erlang gives you the benefits of asynchronous network
149 communcation without using callbacks. Here is a trivial example of a long-poll
150 controller:
151
152 longpoll('GET', [Channel]) ->
153 {ok, Timestamp, Messages} = boss_mq:pull(Channel, last),
154 {json, [{timestamp, Timestamp}, {messages, Messages}]}.
155
156 The call to `pull` blocks until a message is received. Because processes are
157 cheap in Erlang, the overhead of keeping alive a blocking request is very small
158 (just a few kilobytes of memory, compared to megabytes in Rails). You can
159 thus keep alive thousands of Comet request with just a few megabytes of memory.
160 Also notice that the controller logic remains nice and clean (no callbacks). We
161 can perform an arbitrary number of network requests without increasing the
162 scope level.
163
164 *Events*. An interesting feature of Chicago Boss is the events API called
165 BossNews. With it, you can watch a record or a set of records for changes,
166 then execute a callback when a change is witnessed. Combined with long-polling,
167 you can provide a real-time view of your database on your website. Events can
168 also be used to provide a clean separation of business logic and notification
169 logic.
170
171 *Tests*. Chicago Boss has a kick-ass testing framework. Once you try it you
172 won't go back. That's all I'll say for now.
173
174
175 Future Work
176 -----------
177
178 Most of Chicago Boss's planned features have been implemented at this point. It
179 hasn't really been tested in a distributed environment, but it's already
180 running on a few public-facing websites, and many more internal websites (or so
181 I am told). It would be nice to add more databases (such as CouchDB and Oracle)
182 and support horizontal sharding. The last main feature before 1.0 will be
183 the ability to distribute apps written in Chicago Boss as standalone OTP
184 applications.
185
186
187 Further Reading
188 ---------------
189
92aa322 @evanmiller Documentation for the config file
evanmiller authored
190 See the FAQ and API files located at
191
c0e0ea2 @evanmiller Fix links
evanmiller authored
192 <http://www.chicagoboss.org/>
13ed21b Update README with new resources
Evan Miller authored
193
194 If you need help getting started, check out "An Evening With Chicago Boss":
195
c0e0ea2 @evanmiller Fix links
evanmiller authored
196 <http://www.evanmiller.org/chicago-boss-guide.html>
13ed21b Update README with new resources
Evan Miller authored
197
198 There's also the mailing list:
199
c0e0ea2 @evanmiller Fix links
evanmiller authored
200 <http://groups.google.com/group/chicagoboss>
Something went wrong with that request. Please try again.