Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Newer
Older
100644 247 lines (184 sloc) 10.157 kb
61e27b1 @sstephenson Begin work on the manual
sstephenson authored
1 Pow: Zero-configuration Rack server for Mac OS X
2 ================================================
3
4 **Pow is a zero-configuration Rack server for Mac OS X.** It makes
7aa210d @sstephenson I don't like the way this sounded
sstephenson authored
5 developing Rails and Rack applications as frictionless as
6 possible. You can install it in ten seconds and have your first app up
7 and running in under a minute. No mucking around with `/etc/hosts`, no
8 compiling Apache modules, no editing configuration files or installing
9 preference panes. And running multiple apps with multiple versions of
10 Ruby is trivial.
61e27b1 @sstephenson Begin work on the manual
sstephenson authored
11
12 How does it work? A few simple conventions eliminate the need for
13 tedious configuration. Pow runs as your user on an unprivileged port,
14 and includes both an HTTP and a DNS server. The installation process
15 sets up a firewall rule to forward incoming requests on port 80 to
16 Pow. It also sets up a system hook so that all DNS queries for a
2e36cba @sstephenson Switch to `dev` for the default top-level domain
sstephenson authored
17 special top-level domain (`.dev`) resolve to your local machine.
61e27b1 @sstephenson Begin work on the manual
sstephenson authored
18
19 To serve a Rack app, just symlink it into your `~/.pow`
20 directory. Let's say you're working on an app that lives in
21 `~/Projects/myapp`. You'd like to access it at
2e36cba @sstephenson Switch to `dev` for the default top-level domain
sstephenson authored
22 `http://myapp.dev/`. Setting it up is as easy as:
61e27b1 @sstephenson Begin work on the manual
sstephenson authored
23
24 $ cd ~/.pow
25 $ ln -s ~/Projects/myapp
26
46602cb @sstephenson Installation
sstephenson authored
27 That's it! The name of the symlink (`myapp`) determines the hostname
2e36cba @sstephenson Switch to `dev` for the default top-level domain
sstephenson authored
28 you use (`myapp.dev`) to access the application it points to
46602cb @sstephenson Installation
sstephenson authored
29 (`~/Projects/myapp`).
61e27b1 @sstephenson Begin work on the manual
sstephenson authored
30
31 ## Installation
32
46602cb @sstephenson Installation
sstephenson authored
33 Pow requires Mac OS X version 10.6 or newer. To install or upgrade
34 Pow, just open a terminal and run this command:
35
36 $ curl get.pow.cx | sh
37
38 You can [review the install script](http://get.pow.cx/) yourself
39 before running it, if you'd like. Always a good idea.
40
41 The installer unpacks the latest Pow version into
42 `~/Library/Application Support/Pow/Versions` and points the
43 `~/Library/Application Support/Pow/Current` symlink there. It also
44 installs
45 [launchd](http://developer.apple.com/library/mac/#documentation/Darwin/Reference/ManPages/man8/launchd.8.html)
46 scripts for your user (the Pow server itself) and for the system (to
47 set up the `ipfw` rule), if necessary. Then it boots the server.
48
49 **Note**: The firewall rule installed by Pow redirects all incoming
50 traffic on port 80 to port 20559, where Pow runs. This means if you
51 have another web server running on port 80, like the Apache that
52 comes with Mac OS X, it will be inaccessible without either
53 disabling the firewall rule or updating that server's configuration
54 to listen on another port.
55
61e27b1 @sstephenson Begin work on the manual
sstephenson authored
56 ## Managing Applications
57
71ba6ba @sstephenson Begin documenting apps
sstephenson authored
58 Pow deals exclusively with Rack applications. For the purposes of this
6590987 @sstephenson Virtual hosts
sstephenson authored
59 document, a _Rack application_ is a directory with a `config.ru`
60 rackup file (and optionally a `public` subdirectory containing static
71ba6ba @sstephenson Begin documenting apps
sstephenson authored
61 assets). For more information on rackup files, see the [Rack::Builder
62 documentation](http://rack.rubyforge.org/doc/Rack/Builder.html).
63
64 Pow automatically spawns a worker process for an application the first
65 time it's accessed, and will keep up to two workers running for each
66 application. Workers are automatically terminated after 15 minutes of
67 inactivity.
68
2e36cba @sstephenson Switch to `dev` for the default top-level domain
sstephenson authored
69 ### Using virtual hosts and the .dev domain
70
6590987 @sstephenson Virtual hosts
sstephenson authored
71 A _virtual host_ specifies a mapping between a hostname and an
72 application. To install a virtual host, symlink a Rack application
73 into your `~/.pow` directory. The name of the symlink tells Pow which
74 hostname you want to use to access the application. For example, a
75 symlink named `myapp` will be accessible at `http://myapp.dev/`.
76
77 **Note**: The Pow installer creates `~/.pow` as a convenient symlink
78 to `~/Library/Application Support/Pow/Hosts`, the actual location
79 from which virtual host symlinks are read.
80
81 #### Subdomains
82
83 Once a virtual host is installed, it's also automatically accessible
84 from all subdomains of the named host. For example, the `myapp`
85 virtual host described above could also be accessed at
86 `http://www.myapp.dev/` and `http://assets.www.myapp.dev/`. You can
87 override this behavior to, say, point `www.myapp.dev` to a different
88 application — just create another virtual host symlink named
89 `www.myapp` for the application you want.
90
91 #### Multiple virtual hosts
92
93 You might want to serve the same application from multiple hostnames.
94 In Pow, an application may have more than one virtual host. Multiple
95 symlinks that point to the same application will share the same worker
96 processes.
71ba6ba @sstephenson Begin documenting apps
sstephenson authored
97
98 ### Customizing environment variables
99
44961cf @sstephenson Environment variables
sstephenson authored
100 Pow lets you customize the environment in which worker processes
101 run. Before an application boots, Pow attempts to execute two scripts
102 — first `.powrc`, then `.powenv` — in the application's
103 root. Any environment variables exported from these scripts are passed
104 along to Rack.
105
106 For example, if you wanted to adjust the Ruby load path for a
107 particular application, you could modify `RUBYLIB` in `.powrc`:
108
109 export RUBYLIB="app:lib:$RUBYLIB"
110
111 #### Choosing the right environment script
112
113 Pow supports two separate environment scripts with the intention that
114 one may be checked into your source control repository, leaving the
115 other free for any local overrides. If this sounds like something you
116 need, you'll want to keep `.powrc` under version control, since it's
117 loaded first.
118
71ba6ba @sstephenson Begin documenting apps
sstephenson authored
119 ### Working with different versions of Ruby
120
a8106bb @sstephenson Ruby versions and rvm
sstephenson authored
121 Pow offers full support for running multiple applications under
122 different versions of Ruby with
123 [rvm](http://rvm.beginrescueend.com/). Just add a [project
124 `.rvmrc`](http://rvm.beginrescueend.com/workflow/rvmrc/#project)
125 file to your application's root directory and you're good to go.
126
127 For example, to instruct Pow to run an application with Ruby 1.9.2,
128 use this `.rvmrc` file:
129
130 rvm 1.9.2
131
132 If an application has an `.rvmrc` file but rvm isn't installed, Pow
133 will show an error message without booting the app.
134
71ba6ba @sstephenson Begin documenting apps
sstephenson authored
135 ### Serving static files
136
f4eabb6 @sstephenson Static files and sites
sstephenson authored
137 Pow automatically serves static files in the `public` directory of
138 your application. It's possible to serve a completely static site
139 without a `config.ru` file as long as it has a `public` directory.
140
71ba6ba @sstephenson Begin documenting apps
sstephenson authored
141 ### Restarting applications
142
975c0cf @sstephenson Restarting
sstephenson authored
143 You can tell Pow to restart an application the next time it's
144 accessed. Simply save a file named `restart.txt` in the `tmp`
145 directory of your application (you'll need to create the directory
146 first if it doesn't exist). The easiest way to do this is with the
147 `touch` command:
148
149 touch tmp/restart.txt
150
151 Restarting an application will also reload any environment scripts
152 (`.powrc`, `.powenv`, or `.rvmrc`) before booting the app, so don't
153 forget to touch `restart.txt` if you make changes to these scripts.
154
155 It's also fine to kill worker processes manually — they'll
156 restart the next time you access the virtual host. A handy way to do
157 this is with OS X's Activity Monitor. Select "All Processes,
158 Hierarchically" from the dropdown at the top of the Activity Monitor
159 window. Then find the `pow` process, expand the disclosure triangle,
160 find the Ruby worker process you want to kill, and choose "Quit
161 Process." (You can click "Inspect" on a worker process and choose
162 "Open Files and Ports" to determine which application the process is
163 serving.)
164
71ba6ba @sstephenson Begin documenting apps
sstephenson authored
165 ### Viewing log files
61e27b1 @sstephenson Begin work on the manual
sstephenson authored
166
cf0c77c @sstephenson Log files
sstephenson authored
167 Pow stores log files in the `~/Library/Logs/Pow` directory so they can
168 be viewed easily with OS X's Console application. Each incoming
0571e71 @sstephenson Typos
sstephenson authored
169 request URL is logged, along with its hostname and HTTP method, in the
170 `access.log` file. The stdout and stderr streams for each worker
171 process are captured and logged to the `apps` directory in a file
172 matching the name of the application.
cf0c77c @sstephenson Log files
sstephenson authored
173
174 **Note**: Rails logger output does not appear in Pow's logs. You'll
175 want to `tail -f log/development.log` to see those.
176
9e1da52 @sstephenson Document .powconfig
sstephenson authored
177 ## Configuring Pow
178
179 Pow is designed so that most people will never need to configure
180 it. Sometimes you can't avoid adjusting a setting or two, though. When
181 Pow boots, it executes the `.powconfig` script in your home directory
182 if it's present. You can use this script to set environment variables
183 that will override Pow's default settings.
184
185 For example, this `~/.powconfig` file tells Pow to kill idle
186 applications after 5 minutes (300,000 ms) and spawn 3 workers per app:
187
188 export POW_TIMEOUT=300000
189 export POW_WORKERS=3
190
191 See the [Configuration class
192 documentation](http://pow.cx/docs/configuration.html#section-5) for a
193 full list of settings that you can change.
194
195 **Note**: After modifying a setting in `~/.powconfig`, you'll need to
196 restart Pow for the change to take effect. You can do this by
197 finding the `pow` process in OS X's Activity Monitor and clicking
198 "Quit Process".
199
61e27b1 @sstephenson Begin work on the manual
sstephenson authored
200 ## Contributing
201
0a8cd64 @sstephenson Contributing
sstephenson authored
202 Pow is written in [Node.js](http://nodejs.org/) with
203 [CoffeeScript](http://jashkenas.github.com/coffee-script/). You can
204 read the [annotated source code](http://pow.cx/docs/) to learn about
205 how it works internally. Please report bugs on the [GitHub issue
206 tracker](https://github.com/37signals/pow/issues).
207
208 If you're interested in contributing to Pow, first start by cloning a
209 copy of the Git repository:
210
211 $ git clone https://github.com/37signals/pow.git
212
213 Install the required JavaScript dependencies with
214 [npm](http://npmjs.org/) (you'll need version 1.0 or higher):
215
216 $ cd pow
217 $ npm install --dev
218
219 Run the test suite:
220
221 $ cake test
222
61e27b1 @sstephenson Begin work on the manual
sstephenson authored
223 ## License
224
9d13031 @sstephenson Add license
sstephenson authored
225 (The MIT License)
226
0a8cd64 @sstephenson Contributing
sstephenson authored
227 Copyright © 2011 Sam Stephenson, 37signals
9d13031 @sstephenson Add license
sstephenson authored
228
229 Permission is hereby granted, free of charge, to any person obtaining
230 a copy of this software and associated documentation files (the
231 "Software"), to deal in the Software without restriction, including
232 without limitation the rights to use, copy, modify, merge, publish,
233 distribute, sublicense, and/or sell copies of the Software, and to
234 permit persons to whom the Software is furnished to do so, subject to
235 the following conditions:
236
237 The above copyright notice and this permission notice shall be
238 included in all copies or substantial portions of the Software.
239
240 THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
241 EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
242 MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
243 NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
244 LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
245 OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
246 WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
Something went wrong with that request. Please try again.