README.md in keycard-0.1.1 vs README.md in keycard-0.1.2

@@ -35,12 +35,47 @@
 
 And then execute:
 
     $ bundle
 
-Or install it yourself as:
+## Configuration
 
-    $ gem install keycard
+There are two aspects of Keycard that are configurable: the database for IP
+ranges as they map to institutions (IP blocks map to networks, and networks are
+associated with institutions), and the access mode (whether your application is
+served directly or behind a reverse proxy). These will be unified eventually,
+but for now, they are configured separately.
+
+## For the Database
+
+For the database, there is a Railtie that, when running in a Rails app,
+attempts to use the same connection information as ActiveRecord. If you are
+running in this configuration, you will need to run a `rake db:migrate` to
+create the Keycard tables and add them to your `db/schema.rb`. From there forward,
+running `db:setup` or `db:schema:load` will create these tables for you. There is
+a `keycard:migrate` Rake task if you want to run it separately, but it hooks into
+the Rails `db:migrate` by default for convenience.
+
+If you need to customize the database configuration, which will be typical for
+at least the production environment, the easiest way is to define an
+initializer. In a multi-application environment, the database may be read-only,
+which will require the `Keycard::DB.config` to have its `readonly` property set
+to `true`. You can also set either the `Keycard::DB.config.opts` to the options
+to pass to the Sequel connection or set `Keycard::DB.config.url` to use a
+connction string. The latter is equivalent to setting the `KEYCARD_DATABASE_URL`
+environment variable.
+
+## For the Access Mode
+
+To extract the username and client IP from each request, Keycard must be
+configured for an "access mode". This can be set in an initializer, under the
+`Keycard.config.access` property, and should be either `:direct` if clients
+will make HTTP requests directly to the Ruby webserver, or `:proxy` if a
+reverse proxy will be used.
+
+Under the hood, these modes amount to using either `REMOTE_USER` and
+`REMOTE_ADDR` in the environment set by the Ruby webserver for direct mode or
+the `X-Forwarded-User` and `X-Forwarded-For` headers set by a reverse proxy.
 
 ## License
 
 Keycard is licensed under the BSD-3-Clause license. See [LICENSE.md](LICENSE.md).