Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Newer
Older
100644 249 lines (177 sloc) 9.425 kb
7689680 Prep for 0.6.10
Evan Miller authored
1 Chicago Boss: Start small, dream big
2 ====================================
5dac4a1 Zachary Kessin added travis-ci button
zkessin authored
3 [![Build Status](https://travis-ci.org/zkessin/ChicagoBoss.png?branch=error_reporting)](https://travis-ci.org/zkessin/ChicagoBoss)
d39a1b7 Initial commit of Chicago Boss.
Evan Miller authored
4
7bfef2b Evan Miller Update README
evanmiller authored
5 Chicago Boss is a server framework inspired by Rails and written in Erlang. It
6 offers all the conveniences of modern web development, including Comet. What sets
7 Chicago Boss apart from other non-Erlang frameworks is that it can handle large
8 amounts of traffic without any drop in performance. What sets Chicago Boss apart
9f24895 README update
Evan Miller authored
9 from other Erlang frameworks is that it is easy to set up and use.
7bfef2b Evan Miller Update README
evanmiller authored
10
40b7fc5 Zachary Kessin CB does not work with R16b03, so if it starts with R16b03 die with an er...
zkessin authored
11 WARNING: Chicago Boss hoes not work with Erlang R16B03 due to an error in erl_syntax
7bfef2b Evan Miller Update README
evanmiller authored
12
13 60-second Quickstart
14 --------------------
15
16 After downloading and extracting, type
92aa322 Evan Miller Documentation for the config file
evanmiller authored
17
71b3754 Eduardo Gurgel Add syntax highlighting to README.md
edgurgel authored
18 ```console
19 make
20 make app PROJECT=mynewproject
21 cd ../mynewproject
22 ./init-dev.sh
23 ```
f1d5d2a Michael LaCroix fix links in README
iamlacroix authored
24
6c46d62 rambocoder Updated README.MD Windows Instructions
rambocoder authored
25 For Windows, type
71b3754 Eduardo Gurgel Add syntax highlighting to README.md
edgurgel authored
26
27 ```console
28 windows-make.bat
29 windows-make.bat app PROJECT=mynewproject
30 cd ..\mynewproject
31 start-server.bat
32 ```
74bd246 Evan Miller Update README for new build system
evanmiller authored
33
7bfef2b Evan Miller Update README
evanmiller authored
34 Then visit http://localhost:8001/ in your browser. Congratulations, you have
35 a web server. There will be a lot of PROGRESS REPORTs on your console but
36 everything should be running smoothly.
74bd246 Evan Miller Update README for new build system
evanmiller authored
37
e7c0d58 update README about project names
Evan Miller authored
38 The project name should be a legal Erlang atom, i.e. start with a lowercase
5e1f4a1 Jose Luis Gordo Romero Updated instructions (readme and readme_upgrade)
jgordor authored
39 letter and contain only letters, digits, and underscores (for easy compatibility is recommended name the project dir and app name the same).
e7c0d58 update README about project names
Evan Miller authored
40
74bd246 Evan Miller Update README for new build system
evanmiller authored
41
42 Dependencies
43 ------------
d39a1b7 Initial commit of Chicago Boss.
Evan Miller authored
44
1d4f425 Matthew Moss Update README.md erlang version requirement
mdmoss authored
45 * Erlang R15B or later -
dc3c799 Evan Miller Mail framework; Test docs; Project restructuring
evanmiller authored
46
7ac0ac5 Evan Miller Linkify URLs in README
evanmiller authored
47 <http://www.erlang.org/download.html>
d39a1b7 Initial commit of Chicago Boss.
Evan Miller authored
48
d6347a0 Evan Miller Prep docs for 0.3.6
evanmiller authored
49 * Check with `erlang:system_info(otp_release)`.
c53ee94 Update Medici, serve static files.
Evan Miller authored
50
788d56f Add Medici code to the repository, update Makefiles.
Evan Miller authored
51
02061c5 strobe
strobe authored
52 * On Windows Vista or Windows 7 -
53
6c46d62 rambocoder Updated README.MD Windows Instructions
rambocoder authored
54 * Erlang bin directory must be in PATH.
02061c5 strobe
strobe authored
55
d39a1b7 Initial commit of Chicago Boss.
Evan Miller authored
56
a571b28 Major refactoring to support multiple apps
Evan Miller authored
57 Admin Interface
58 ---------------
59
60 You probably want to install the CB admin interface. Download it from
61
f1d5d2a Michael LaCroix fix links in README
iamlacroix authored
62 <https://github.com/ChicagoBoss/cb_admin>
a571b28 Major refactoring to support multiple apps
Evan Miller authored
63
64
74bd246 Evan Miller Update README for new build system
evanmiller authored
65 Upgrades
66 --------
67
7bfef2b Evan Miller Update README
evanmiller authored
68 Uprading used to be a pain but now it is easy. See README_UPGRADE
74bd246 Evan Miller Update README for new build system
evanmiller authored
69
70
71 Database Setup
72 --------------
d39a1b7 Initial commit of Chicago Boss.
Evan Miller authored
73
7bfef2b Evan Miller Update README
evanmiller authored
74 By default CB uses an in-memory database that needs no configuration. To start
75 working with an actual database, See README_DATABASE
92aa322 Evan Miller Documentation for the config file
evanmiller authored
76
77
9f24895 README update
Evan Miller authored
78 Philosophy and Features
74bd246 Evan Miller Update README for new build system
evanmiller authored
79 -----------------------
92aa322 Evan Miller Documentation for the config file
evanmiller authored
80
9f24895 README update
Evan Miller authored
81 Why another web framework? Because Rails apps are slow and Node apps are messy.
82 Chicago Boss takes advantage of functional programming and under-the-hood
83 compiler magic to provide clean, understandable controller logic, Django-style
84 templates, and an ORM based on Erlang's parameterized modules. The best part is
85 that the network I/O is 100% asynchronous so you can seamlessly integrate Comet
86 endpoints into your app, and you never have to worry about a slow database
91a1981 README typo
Evan Miller authored
87 query dragging down unrelated requests.
9f24895 README update
Evan Miller authored
88
89 CB ships with all the tools you need to build a feature-ful website, including
90 sessions, URL routing, filtering requests and post-processing responses,
91 frameworks for sending and receiving email, JSON generation, Comet via
92 long-poll and message queues, and internationalization (i18n). Read on for
93 details.
94
95 *Databases*. Chicago Boss currently supports MySQL, PostgreSQL, Tokyo Tyrant,
91a1981 README typo
Evan Miller authored
96 Mnesia, MongoDB, and Riak. In CB 0.5.4 and later, you can mix and match
9f24895 README update
Evan Miller authored
97 databases by configuring Boss to use vertical shards. For SQL databases, the
98 conventions are similar to Rails (plural nouns for the table names, object_id
99 for foreign keys, etc.).
100
101 *BossRecords*. Boss's take on ActiveRecord is called a BossRecord, which is
102 an Erlang parameterized module on steroids. You instantiate a BossRecord like
103 a regular parameterized module:
104
71b3754 Eduardo Gurgel Add syntax highlighting to README.md
edgurgel authored
105 ```erlang
106 Article = article:new('id', "This is a title", "This is a body")
107 ```
9f24895 README update
Evan Miller authored
108
109 But then CB generates functions and attaches them to BossRecords, so you can
110 write code like
111
71b3754 Eduardo Gurgel Add syntax highlighting to README.md
edgurgel authored
112 ```erlang
113 {ok, SavedArticle} = Article:save()
114 ```
9f24895 README update
Evan Miller authored
115
116 Before saving to the database, the save() function will call a function called
117 validation_tests(), where you can perform custom validation logic.
118
119 CB also generates getter functions which can be invoked directly in templates,
120 so in your template you can write things like
121
71b3754 Eduardo Gurgel Add syntax highlighting to README.md
edgurgel authored
122 ```erlang
123 {{ article.title }}
124 ```
9f24895 README update
Evan Miller authored
125
126 Speaking of which...
127
128 *Templates*. Chicago Boss uses ErlyDTL, an Erlang implentation of Django template
129 language. In fact, Chicago Boss originated with a rewrite of ErlyDTL, and the same
130 person maintains both projects so you always get the latest ErlyDTL features. Templates
131 can access and loop over values stored in proplists, dictionaries, and BossRecords,
132 so you can move data from the database to your templates with a minimum of massaging.
133
134 In addition, templates are tightly integrated with Boss's i18n machinery. The admin
135 interface automatically parses templates for translatable strings, and Boss can
136 choose which language to serve based on the request's Accept-Languages header and
137 the calculated translation coverage for a particular page. Multi-language websites
138 are easy to develop with Chicago Boss.
139
140 *Controllers*. Erlang's pattern-matching is a perfect fit for writing
141 controller logic. Your controllers are passed the URL method (GET, POST) and a list
142 of URL tokens, and just need to return a tuple telling Boss what to do, for example:
143
144 * `{ok, Variables}` - render the default template with Variables
145 * `{render_other, Variables}` - render another template
146 * `{redirect, URL}` - redirect the request
147 * `{json, Proplist}` - encode the Proplist as JSON and send to the client
148 * `{output, Data}` - send Data to the client
149
150 If you come from Rails, you'll instantly notice the benefit of Erlang's
151 language design: you don't need an ugly `case request.method` statement inside
152 every action, you never have atrocities like `render and return`, and you can
153 always see every variable that is in scope. In CB apps, controller logic is
6823f06 Typo in README
Evan Miller authored
154 always concise and usually a pleasure to read.
9f24895 README update
Evan Miller authored
155
156 *Sessions*. You can configure sessions to be stored in memory (ETS) or in an
157 Mnesia database. The `boss_session` and `boss_flash` modules provide functions
158 for storing and retrieving session information.
159
160 *Routes*. By default, Chicago Boss uses the same routing conventions as Ruby on
161 Rails (`/controller/action/id`). You can customize the routes and provide
a571b28 Major refactoring to support multiple apps
Evan Miller authored
162 a base URL in the priv/application.routes file. Of course, most routing occurs
163 with the pattern-matching controller logic, e.g.
71b3754 Eduardo Gurgel Add syntax highlighting to README.md
edgurgel authored
164 ```erlang
165 posts('GET', ["category", Category]) ->
166 ```
9f24895 README update
Evan Miller authored
167
a571b28 Major refactoring to support multiple apps
Evan Miller authored
168 You can then generate URLs to match controller patterns in your templates like
169 so:
170
171 {% url action="posts" category="some category" %}
172
9f24895 README update
Evan Miller authored
173 *Email*. Chicago Boss ships with a miniature MVC for sending multipart emails.
174 Emails can be templated with ErlyDTL, and it is easy to provide plain-text and
175 HTML versions of the same email. In testing environments, email can be sent
0019f88 Prep for 0.5.4
Evan Miller authored
176 directly to the recipient, or in production can be relayed to an SMTP server.
9f24895 README update
Evan Miller authored
177
178 A Chicago Boss server can also receive email over SMTP. Each email address maps
179 to a function in your incoming mail controller, so it is easy to write
180 well-organized email applications. Your email controller has access to the
181 exact same resources as your web controllers, including database requests,
182 BossRecord instantiation, and the message queue; web and email are fully
183 integrated.
184
185 *Comet*. It's simple to write a Comet endpoint in Chicago Boss. Unlike any
186 other language, Erlang gives you the benefits of asynchronous network
187 communcation without using callbacks. Here is a trivial example of a long-poll
188 controller:
189
71b3754 Eduardo Gurgel Add syntax highlighting to README.md
edgurgel authored
190 ```erlang
191 longpoll('GET', [Channel]) ->
192 {ok, Timestamp, Messages} = boss_mq:pull(Channel, last),
193 {json, [{timestamp, Timestamp}, {messages, Messages}]}.
194 ```
9f24895 README update
Evan Miller authored
195
196 The call to `pull` blocks until a message is received. Because processes are
197 cheap in Erlang, the overhead of keeping alive a blocking request is very small
198 (just a few kilobytes of memory, compared to megabytes in Rails). You can
199 thus keep alive thousands of Comet request with just a few megabytes of memory.
200 Also notice that the controller logic remains nice and clean (no callbacks). We
0019f88 Prep for 0.5.4
Evan Miller authored
201 can perform an arbitrary sequence of asynchronous network requests without
202 increasing the scope level.
9f24895 README update
Evan Miller authored
203
204 *Events*. An interesting feature of Chicago Boss is the events API called
205 BossNews. With it, you can watch a record or a set of records for changes,
206 then execute a callback when a change is witnessed. Combined with long-polling,
207 you can provide a real-time view of your database on your website. Events can
208 also be used to provide a clean separation of business logic and notification
209 logic.
210
211 *Tests*. Chicago Boss has a kick-ass testing framework. Once you try it you
212 won't go back. That's all I'll say for now.
213
214
215 Future Work
216 -----------
217
218 Most of Chicago Boss's planned features have been implemented at this point. It
219 hasn't really been tested in a distributed environment, but it's already
220 running on a few public-facing websites, and many more internal websites (or so
221 I am told). It would be nice to add more databases (such as CouchDB and Oracle)
222 and support horizontal sharding. The last main feature before 1.0 will be
223 the ability to distribute apps written in Chicago Boss as standalone OTP
224 applications.
225
226
227 Further Reading
228 ---------------
229
92aa322 Evan Miller Documentation for the config file
evanmiller authored
230 See the FAQ and API files located at
231
c0e0ea2 Evan Miller Fix links
evanmiller authored
232 <http://www.chicagoboss.org/>
13ed21b Update README with new resources
Evan Miller authored
233
5e1f4a1 Jose Luis Gordo Romero Updated instructions (readme and readme_upgrade)
jgordor authored
234 If you need help getting started, check the new pdf tutorial:
13ed21b Update README with new resources
Evan Miller authored
235
5e1f4a1 Jose Luis Gordo Romero Updated instructions (readme and readme_upgrade)
jgordor authored
236 <http://www.chicagoboss.org/tutorial.pdf>
13ed21b Update README with new resources
Evan Miller authored
237
ad1376c Vitor Pellegrino Adding Wiki to the README
pellegrino authored
238 Be sure to also check the wiki
239
f1d5d2a Michael LaCroix fix links in README
iamlacroix authored
240 <https://github.com/ChicagoBoss/ChicagoBoss/wiki>
ad1376c Vitor Pellegrino Adding Wiki to the README
pellegrino authored
241
13ed21b Update README with new resources
Evan Miller authored
242 There's also the mailing list:
243
c0e0ea2 Evan Miller Fix links
evanmiller authored
244 <http://groups.google.com/group/chicagoboss>
6d19989 Zachary Kessin added Coding standards link
zkessin authored
245
f1d5d2a Michael LaCroix fix links in README
iamlacroix authored
246 If you want to contribute to CB
6d19989 Zachary Kessin added Coding standards link
zkessin authored
247
f1d5d2a Michael LaCroix fix links in README
iamlacroix authored
248 [CODING_STANDARDS.md](https://github.com/ChicagoBoss/ChicagoBoss/blob/master/CODING_STANDARDS.md)
Something went wrong with that request. Please try again.