Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Newer
Older
100644 110 lines (81 sloc) 4.463 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
59 document, a Rack application is a directory with a `config.ru` rackup
60 file (and optionally a `public` subdirectory containing static
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
71 A virtual host specifies a mapping between a hostname and an
72 application. (An application may have more than one virtual host.)
71ba6ba @sstephenson Begin documenting apps
sstephenson authored
73
74 ### Customizing environment variables
75
76 ### Working with different versions of Ruby
77
78 ### Serving static files
79
80 ### Restarting applications
81
82 ### Viewing log files
61e27b1 @sstephenson Begin work on the manual
sstephenson authored
83
84 ## Contributing
85
86 ## License
87
9d13031 @sstephenson Add license
sstephenson authored
88 (The MIT License)
89
90 Copyright (c) 2011 Sam Stephenson, 37signals
91
92 Permission is hereby granted, free of charge, to any person obtaining
93 a copy of this software and associated documentation files (the
94 "Software"), to deal in the Software without restriction, including
95 without limitation the rights to use, copy, modify, merge, publish,
96 distribute, sublicense, and/or sell copies of the Software, and to
97 permit persons to whom the Software is furnished to do so, subject to
98 the following conditions:
99
100 The above copyright notice and this permission notice shall be
101 included in all copies or substantial portions of the Software.
102
103 THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
104 EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
105 MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
106 NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
107 LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
108 OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
109 WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
Something went wrong with that request. Please try again.