Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

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