Skip to content

HTTPS clone URL

Subversion checkout URL

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