Skip to content

HTTPS clone URL

Subversion checkout URL

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