Merge branch 'gh-pages-deploy-docs' into gh-pages

1 files changed, 102 insertions, 0 deletions

diff --git a/glossary.md b/glossary.md
index d641f7451..25a3034bc 100644
--- a/glossary.md
+++ b/glossary.md
@@ -18,15 +18,19 @@ Definitions
   <li><a href="#alaveteli">Alaveteli</a></li>
   <li><a href="#agnostic">asker agnostic</a></li>
   <li><a href="#authority">authority</a></li>
+  <li><a href="#capistrano">Capistrano</a></li>
+  <li><a href="#development">development site</a></li>
   <li><a href="#foi">freedom of information</a></li>
   <li><a href="#git">git</a></li>
   <li><a href="#holding_pen">holding pen</a></li>
   <li><a href="#mta">MTA</a></li>
+  <li><a href="#production">production site</a></li>
   <li><a href="#publish">publish</a></li>
   <li><a href="#request">request</a></li>
   <li><a href="#response">response</a></li>
   <li><a href="#rails">Ruby&nbsp;on&nbsp;Rails</a></li>
   <li><a href="#sass">Sass</a></li>
+  <li><a href="#staging">staging site</a></li>
   <li><a href="#state">state</a></li>
   <li><a href="#theme">theme</a></li>
 </ul>
@@ -107,6 +111,46 @@ Definitions
   </dd>
 
   <dt>
+    <a name="capistrano">Capistrano</a>
+  </dt>
+  <dd>
+	  <strong>Capistrano</strong> is a remote server automation and deployment tool written in Ruby.
+    Alaveteli's deployment mechanism, which is optional, uses it. 
+    <div class="more-info">
+      <p>More information:</p>
+      <ul>
+        <li>
+          how to <a href="{{ site.baseurl }}installing/deploy">deploy Alaveteli</a> (and why it's
+          a good idea)
+        </li>
+        <li>
+         The <a href="http://capistranorb.com/">Capistrano website</a> has thorough documentation
+         about the tool
+        </li>
+      </ul>
+    </div>
+  </dd>
+
+  <dt>
+    <a name="development">development site</a> (also: dev, development server)
+  </dt>
+  <dd>
+    A <strong>dev server</strong> is one that is running your Alaveteli site
+    so you can <a href="{{ site.baseurl }}customising/">customise it</a>, experiment
+    with different settings, and test that it does what you expect.
+    This is different from a 
+    <a href="#production" class="glossary">production server</a>, which is the one your
+    users actually visit running with live data, or a
+    <a href="#staging" class="glossary">staging server</a>,
+    which is used for testing code before it goes live.
+    <p>
+      On your dev server, you should set
+      <code><a href="{{site.baseurl}}customising/config/#staging_site">STAGING_SITE</a></code>
+      to <code>1</code>.
+    </p>
+  </dd>
+
+  <dt>
     <a name="foi">Freedom of Information</a> (also FOI)
   </dt>
   <dd>
@@ -203,6 +247,37 @@ Definitions
   </dd>
 
   <dt>
+    <a name="production">production site</a> (also: live, production server)
+  </dt>
+  <dd>
+    A <strong>production server</strong> is one that is running your Alaveteli site
+    for real users, with live data. This is different from a 
+    <a href="#development" class="glossary">development server</a>, which you use make your
+    customisation and environment changes and try to get them to all work OK, or a 
+    <a href="#staging" class="glossary">staging server</a>, which is used for testing code
+    and configuration after it's been finished but before it goes live.
+    <p>
+      Your production site should be configured to run as efficiently as possible: for
+      example, caching is enabled, and debugging switched off.
+      <a href="#rails" class="glossary">Rails</a> has a "production mode" which does
+      this for you: set
+      <code><a href="{{site.baseurl}}customising/config/#staging_site">STAGING_SITE</a></code>
+      to <code>0</code>. Note that if you <em>change</em> this setting after you've
+      deployed, the <code>rails_env.rb</code> file that enables Rails's production
+      mode won't be created until you run <code>rails-post-deploy</code>.
+    <p>
+      If you have a staging server, the system environment of your staging and
+      production servers should be identical.
+    </p>
+    <p>
+      You should never need to edit code directly on your production server.
+      We strongly recommend you use Alaveteli's 
+      <a href="{{ site.baseurl }}installing/deploy/">deployment mechanism</a>
+      (using Capistrano) to make changes to your production site.
+    </p>
+  </dd>
+
+  <dt>
     <a name="publish">publish</a>
   </dt>
   <dd>
@@ -286,6 +361,33 @@ Definitions
   </dd>
 
   <dt>
+    <a name="staging">staging server</a> (also: staging site)
+  </dt>
+  <dd>
+    A <strong>staging server</strong> is one that you use for testing code or configuration
+    before it goes live. This is different from a <a href="#development"
+    class="glossary">development server</a>, on which you change the code and settings to
+    make everything work, or the
+    <a href="#production" class="glossary">production server</a>, which is the
+    site your users visit running with live data.
+    <p>
+      On your staging server, you should set
+      <code><a href="{{site.baseurl}}customising/config/#staging_site">STAGING_SITE</a></code>
+      to <code>1</code>.
+    </p>
+    <p>
+      If you have a staging server, the system environment of your staging and
+      production servers should be identical.
+    </p>
+    <p>
+      You should never need to edit code directly on your production or staging servers.
+      We strongly recommend you use Alaveteli's 
+      <a href="{{ site.baseurl }}installing/deploy/">deployment mechanism</a>
+      (using Capistrano) to make changes to these sites.
+    </p>
+  </dd>
+
+  <dt>
     <a name="state">state</a>
   </dt>
   <dd>