From a1cd422e0a40e773a2d0c09117d782a938d69de0 Mon Sep 17 00:00:00 2001
From: Adam Wiggins <adam@heroku.com>
Date: Fri, 3 Jun 2011 02:23:24 -0700
Subject: [PATCH] config section

---
 content/config.md | 16 ++++++++++++++++
 content/toc.md    |  2 +-
 public/style.css  | 24 ++++++++++++++++++++++++
 views/factor.erb  |  3 +++
 web.rb            | 14 ++++++++++++++
 5 files changed, 58 insertions(+), 1 deletion(-)
 create mode 100644 content/config.md

diff --git a/content/config.md b/content/config.md
new file mode 100644
index 0000000..c3ff1a3
--- /dev/null
+++ b/content/config.md
@@ -0,0 +1,16 @@
+## III. Config
+### Store config in the environment
+
+*Config* of the app includes URLs to [attached resources](#) such as the app's database (including user/password, host, and database name), credentials to external services such as Amazon S3, or values such as the canonincal hostname of the app (used for redirects).
+
+A twelve-factor app always strictly separates config from code.  Config varies substantially across deploys, code does not.  A good measure of whether an app is correctly factored on this point is whether it could be released as open source without compromising any credentials.
+
+Developrs have a tendency to want to write config as constants in the code (poor factoring) or into a parseable config file such as `config/database.yml` in Rails (better, but still weak).
+
+Config belongs in *environment variables* (often shortened to *env vars* or *env*).  Env vars are easy to change between deploys and there is no chance of them being checked into the code repo accidentally.
+
+A common pattern with env vars is to fall back on sensible defaults when not set.  For example, an app may use the `CANONICAL_HOST` env var for redirects, but the app will not attempt a redirect the the value is not set (which is usually desirable for development deploys).  Or assuming a local memcached if the MEMCACHED_URL is not set.  In this way, no env vars means the app is running as a vanilla development deploy.
+
+Environment variables are highly granular when compared to the config-file method.  Config files tend to batch up values into named groups often called environments (for example, `development`, `test`, and `production` in Rails).  As more deploys of the app are created, new environment names are necessary - for example, `staging` or `qa`.  As the project grows further, developers may add their own special environments like `joes-staging`.  The worst outcome of this is when the application begins using conditionals to change behavior based on the environment name - for example, deciding to redirect to a hardcoded canonical hostname `if Rails.environment == 'production'`.
+
+This confusing explosion of config is not compatible with neat factoring of twelve-factor apps.  Config vars are each orthogonal values, not grouped together as "environments," but independently controllable for each deploy.  This is a model that scales up smoothly as the app naturally grows more deploys over its lifetime.
diff --git a/content/toc.md b/content/toc.md
index 4a9d20a..5908c13 100644
--- a/content/toc.md
+++ b/content/toc.md
@@ -7,7 +7,7 @@ The Twelve Factors
 ## [II. Dependencies](/dependencies)
 ### Explicit dependency declaration and isolation
 
-## III. Config
+## [III. Config]
 ### Store config in the environment
 
 ## IV. Backing Services
diff --git a/public/style.css b/public/style.css
index 969e1fa..2f47aa9 100644
--- a/public/style.css
+++ b/public/style.css
@@ -75,6 +75,10 @@ section#toc h3 {
   font-weight: normal;
 }
 
+section#factor {
+  margin-top: 24pt;
+  margin-bottom: 128pt;
+}
 section#factor h2 {
   font-size: 32pt;
   margin-bottom: 12pt;
@@ -86,6 +90,26 @@ section#factor h3 {
   margin-bottom: 16pt;
 }
 
+#next, #prev {
+  margin-top: 32pt;
+}
+#next {
+  float: right;
+}
+#prev {
+  float: left;
+}
+#next a, #prev a {
+  font-size: 22pt;
+  text-decoration: none;
+}
+
+code {
+  border: 1px solid #999;
+  background: #eee;
+  padding: 1pt 3pt;
+}
+
 footer {
   color: #444;
   font-size: 12pt;
diff --git a/views/factor.erb b/views/factor.erb
index 686bd10..b03e07c 100644
--- a/views/factor.erb
+++ b/views/factor.erb
@@ -1,5 +1,8 @@
 <section id="factor">
   <article>
     <%= render_markdown(@factor) %>
+
+    <div id="prev"><%= render_prev(@factor) %></div>
+    <div id="next"><%= render_next(@factor) %></div>
   </article>
 </section>
diff --git a/web.rb b/web.rb
index e0541f1..89651e8 100644
--- a/web.rb
+++ b/web.rb
@@ -5,6 +5,8 @@ get '/' do
   erb :home
 end
 
+TOC = %w(repo dependencies config)
+
 get '/:factor' do |factor|
   @factor = factor
   erb :factor
@@ -17,6 +19,18 @@ helpers do
   rescue Errno::ENOENT
     halt 404
   end
+
+  def render_prev(factor)
+    idx = TOC.index(factor)
+    return if idx == 0
+    "<a href=\"/#{TOC[idx-1]}\">&laquo; Previous</a>"
+  end
+
+  def render_next(factor)
+    idx = TOC.index(factor)
+    return if idx == TOC.size-1
+    "<a href=\"/#{TOC[idx+1]}\">Next &raquo;</a>"
+  end
 end
 
 not_found do