In Practice html and styling, example content in config

content/config-in-practice.md

@@ -0,0 +1,32 @@
+## Example: Canonical host config
+
+[`rack-canonical-host`](https://github.com/tylerhunt/rack-canonical-host) is of Rack middleware for Ruby web apps which redirects the user to the canonical hostname for the app.  For example, if your production deploy can be reached at both hostnames `www.example.com` and `example.com`, but you wish for `www.example.com` to be the canonical host, using `rack-canonical-host` will automatically redirect users there when they access it on `example.com`.
+
+## Doing it wrong #1: Hostname as a constant in the code
+
+    CANONICAL_HOST = 'www.example.com'
+    use(Rack::CanonicalHost, CANONICAL_HOST)
+
+This violates twelve-factor because it stores config in the codebase.
+
+## Doing it wrong #2: Hostname from conditional on "environment"
+
+    use Rack::CanonicalHost do
+      case ENV['RACK_ENV'].to_sym
+        when :staging then 'example.com'
+        when :production then 'staging.example.com'
+      end
+    end
+
+This violates twelve-factor because it uses a conditional on the RACK_ENV value which stores an deploy name like `staging` or `production`.  This stores config in the codebase (the hardcoded hostnames), and uses a non-granular, non-orthogonal deploy name to choose the canonical host.  Both of these things make it impossible to add new deploys without changing the code.  (As a thought experiment, imagine what it would take to open-source an app that had the above block of code in it.)
+
+## Doing it right: Hostname from an env var
+
+    use(Rack::CanonicalHost, ENV['CANONICAL_HOST']) if ENV['CANONICAL_HOST']
+
+## Doing it really right: Library uses env var directly
+
+A well-written library of the nature of `rack-canonical-host` will use the enviroment variable directly, simplifying the code even further:
+
+    use Rack::CanonicalHost
+

content/config.md

@@ -18,4 +18,3 @@ One method of managing config is batching it up into named groups (often called
 In a twelve-factor app, env 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.
 
 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.
-

public/style.css

@@ -21,7 +21,6 @@ header {
   font-size: 22pt;
   text-align: center;
   box-shadow: 0px 2px 12px #888;
-  margin-bottom: 12pt;
 }
 header a {
   text-decoration: none;
@@ -36,7 +35,7 @@ section h1 {
   font-size: 22pt;
 }
 
-article {
+article, nav {
   text-align: justify;
   width: 60em;
 }
@@ -49,35 +48,34 @@ article p a:hover, article li a:hover {
   color: #337;
 }
 
-section#toc {
+section.concrete {
   background: #ccc;
   margin-top: 24pt;
   padding-top: 32pt;
   padding-bottom: 32pt;
 }
-section#toc h1 {
+section.concrete h1 {
   font-size: 32pt;
   margin-bottom: 30pt;
   text-decoration: underline;
 }
-section#toc h2 {
+section.concrete h2 {
   margin-top: 12pt;
 }
-section#toc h2 a {
+section.concrete h2 a {
   text-decoration: none;
   color: #000;
 }
-section#toc h2 a:hover {
+section.concrete h2 a:hover {
   color: #337;
 }
-section#toc h3 {
+section.concrete h3 {
   color: #555;
   font-weight: normal;
 }
 
 section#factor {
   margin-top: 24pt;
-  margin-bottom: 128pt;
 }
 section#factor h2 {
   font-size: 32pt;
@@ -90,16 +88,16 @@ section#factor h3 {
   margin-bottom: 16pt;
 }
 
-#next, #prev {
+nav {
   margin-top: 32pt;
 }
-#next {
+nav #next {
   float: right;
 }
-#prev {
+nav #prev {
   float: left;
 }
-#next a, #prev a {
+nav #next a, nav #prev a {
   font-size: 22pt;
   text-decoration: none;
   color: #555;

views/factor.erb

@@ -1,8 +1,22 @@
-<section id="factor">
+<section class="abstract" id="factor">
   <article>
     <%= render_markdown(@factor) %>
-
-    <div id="prev"><%= render_prev(@factor) %></div>
-    <div id="next"><%= render_next(@factor) %></div>
   </article>
 </section>
+
+<section class="concrete" id="in-practice">
+  <article id="in-practice">
+    <%
+      in_practice = render_markdown(@factor + '-in-practice')
+      if in_practice
+    %>
+      <h1>In Practice</h1>
+      <%= in_practice %>
+    <% end %>
+  </article>
+
+  <nav>
+    <div id="prev"><%= render_prev(@factor) %></div>
+    <div id="next"><%= render_next(@factor) %></div>
+  </nav>
+</section>

views/home.erb

@@ -1,19 +1,10 @@
-<section id="abstract">
-  <article>
-    <%= render_markdown('abstract') %>
-  </article>
+<section class="abstract">
+  <article><%= render_markdown('abstract') %></article>
+  <article><%= render_markdown('who') %></article>
 </section>
 
-<section id="who">
-  <article>
-    <%= render_markdown('who') %>
-  </article>
-</section>
-
-<section id="toc">
-  <article>
-    <%= render_markdown('toc') %>
-  <article>
+<section class="concrete">
+  <article><%= render_markdown('toc') %><article>
 </section>
 
 <footer>

web.rb

@@ -8,6 +8,7 @@ end
 TOC = %w(codebase dependencies config backing-services build-release-run processes port-binding concurrency dev-prod-parity logs admin-processes)
 
 get '/:factor' do |factor|
+  halt 404 unless TOC.include?(factor)
   @factor = factor
   erb :factor
 end
@@ -17,7 +18,7 @@ helpers do
     markdown = File.read("content/#{file}.md")
     Maruku.new(markdown).to_html
   rescue Errno::ENOENT
-    halt 404
+    puts "No content for #{file}, skipping"
   end
 
   def render_prev(factor)