diff options
| -rw-r--r-- | _layouts/page.html | 1 | ||||
| -rw-r--r-- | glossary.md | 64 | ||||
| -rw-r--r-- | installing/deploy.md | 78 | ||||
| -rw-r--r-- | installing/index.md | 52 |
4 files changed, 186 insertions, 9 deletions
diff --git a/_layouts/page.html b/_layouts/page.html index 6f060d252..382c6875f 100644 --- a/_layouts/page.html +++ b/_layouts/page.html @@ -18,6 +18,7 @@ layout: default <li><a href="{{ site.baseurl }}getting_started">Getting Started</a></li> <li><a href="{{ site.baseurl }}installing/">Installing</a> <ul> + <li><a href="{{ site.baseurl }}installing/deploy">Deploying</a></li> <li><a href="{{ site.baseurl }}installing/script">Install script</a></li> <li><a href="{{ site.baseurl }}installing/ami">Alaveteli AMI for EC2</a></li> <li><a href="{{ site.baseurl }}installing/manual_install">Installing by hand</a></li> diff --git a/glossary.md b/glossary.md index d641f7451..e65586427 100644 --- a/glossary.md +++ b/glossary.md @@ -18,15 +18,18 @@ 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="#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 on 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 +110,20 @@ Definitions </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. + </dd> + + <dt> <a name="foi">Freedom of Information</a> (also FOI) </dt> <dd> @@ -203,6 +220,31 @@ 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. + <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 +328,28 @@ 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 all work OK, or the + <a href="#production" class="glossary">production server</a>, which is the + site your users visit running with live data. + <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> diff --git a/installing/deploy.md b/installing/deploy.md new file mode 100644 index 000000000..49e960a32 --- /dev/null +++ b/installing/deploy.md @@ -0,0 +1,78 @@ +--- +layout: page +title: Deploying +--- + +# Deploying Alaveteli + +<p class="lead"> + Although you can install Alaveteli and just change it when you need it, we + recommend you adopt a way of <strong>deploying</strong> it automatically, + especially on your <a href="{{ site.baseurl }}glossary/#production">production server</a>. + Alaveteli provides a deployment mechanism using Capistrano. +</p> + +## Why deploy? + +Although you can install Alaveteli in a number of ways, once you're running, +sooner or later you'll need to make changes to the site. A common example is +updating your site when we issue a new release. + +The deployment mechanism takes care of putting all the right files into the +right place, so when you need to put changes live, there's no risk of you +forgetting the update all the files you've changed, or breaking the +configuration by accident. Instead, deployment does all this for you +automatically. It's also more efficient because it is faster than making +changes or copying files by hand, so your site will be down for the shortest +possible time. + +We **strongly recommend** you use the deployment mechanism for your +<a href="{{ site.baseurl }}glossary/#production">production server</a> and, if +you're running one, your +<a href="{{ site.baseurl }}glossary/#staging">staging server</a> too. + +## Capistrano + +Capistrano is included as part of Alaveteli as a standard deployment system. + +### Set up + +First you need to customise your deployment settings, for example the name of the +server you're deploying to. Copy the example file `config/deploy.yml.example` to +`config/deploy.yml` and edit the settings to +suit you. + +These are the general steps required to set up the deployment mechanism. Capistrano +requires things to be set up at both ends -- that is, on the server where you want +Alaveteli to run, and on your own machine (and on the machines of anyone in your team +who you want to be able to deploy): + +* Install packages from `config/packages` +* Install Postgres and configure a user +* Create a directory to deploy to and make sure your deployment user can write to it +* Run `cap deploy:setup` to create directories, etc. +* Run `cap deploy:update_code` so that we've got a copy of the example config on the server. This process will take a long time installing gems, etc. it will also fail on `rake:themes:install` but that's OK +* SSH to the server, change to the `deploy_to` directory +* `cp releases/[SOME_DATE]/config/general.yml-example shared/general.yml` +* `cp releases/[SOME_DATE]/config/database.yml-example shared/database.yml` +* Edit those files to match your required settings +* Back on your machine run `cap deploy` and it should successfully deploy +* Run the DB migrations `cap deploy:migrate` +* Build the Xapian DB `cap xapian:rebuild_index` +* Configure Apache/Passenger with a DocumentRoot of `your_deploy_to/current/public` +* Phew. Time to admire your work by browsing to the server! + + +### Usage + +Ensure you've got a `config/deploy.yml` file with the correct settings for your +site. You'll need to share this with everyone in your team that deploys so it +might be a good idea to keep the latest version in a +[Gist](http://gist.github.com/). + +To deploy to staging just run `cap deploy` but if you want to deploy to +production you need to run `cap -S stage=production deploy`. + +For additional usage instructions, see the [Capistrano +wiki](https://github.com/capistrano/capistrano/wiki/). + diff --git a/installing/index.md b/installing/index.md index 32ed821ea..6708fa99c 100644 --- a/installing/index.md +++ b/installing/index.md @@ -1,28 +1,62 @@ --- layout: page -title: Installing +title: Deploying --- -# Installing Alaveteli +# Deploying Alaveteli <p class="lead"> - - There are a number of ways to install Alaveteli. - We've made an Amazon Machine Image (AMI) so you can quickly deploy on Amazon EC2 (handy if you just want to evaluate it, for example). If you prefer to use your own server, there's an installation script which does most of the work for you. + Although you can install Alaveteli and just change it when you need it, we + recommend you adopt a way of <strong>deploying</strong> it automatically. + This has several advantages, especially for your + <a href="{{ site.baseurl }}glossary/#production">production server</a>. </p> +## Before you start + +This is important: you need to decide if you installing Alaveteli for +[development]({{ site.baseurl }}glossary/#development) or +[production]({{ site.baseurl }}glossary/#production). + +A **development** site is one where you're going to change, customise, and +perhaps experiment while you get it up and running. You should always do this +first. In this environment you can see debug messages, and you don't need to +worry too much about the efficiency and performance of the site (because it's +not really getting lots of traffic). + +A **production** site is different: you want your production site to run as +efficiently as possible, so things like cacheing are swiched on, and debug +messages switched off. It's important to be able to deploy changes to a +production site quickly and efficiently, so we recommend you consider using a +[deployment mechanism]({{ site.baseurl }}installing/deploying/) too. + +Ideally, you should also have a [staging site]({{ site.baseurl }}glossary/#staging), +which is used solely to test new code in an identical environment to your +production site but before it goes live. + +If you're in doubt, you're probably running a development site. Get it up and +running, play with it, customise it, and -- later -- you can install it as a +production server. + +## Deployment + +However, if you're running a production server, we **strongly recommend** you +use the Capistrano [deployment mechanism]({{ site.baseurl }}installing/deploy/) +that's included with Alaveteli. Set this up and you never have to edit files on +those servers, because Capistrano takes care of that for you. + ## Installing the core code * [Install on Amazon EC2]({{ site.baseurl }}installing/ami) using our AMI * [Use the installation script]({{ site.baseurl }}installing/script) which does the full installation on your own server * [Manual installation]({{ site.baseurl }}installing/manual_install) -- step-by-step instructions -If you're setting up a development server on MacOS X, we've also got [MacOS installation instructions]({{ site.baseurl }}installing/macos). +If you're setting up a development server on MacOS X, we've also got +[MacOS installation instructions]({{ site.baseurl }}installing/macos). ## Other installation information -Alaveteli needs to be able to send and receive email, so you need to setup your MTA (Mail Transfer Agent) appropriately. +Alaveteli needs to be able to send and receive email, so you need to setup your +MTA (Mail Transfer Agent) appropriately. * [Installing the MTA]({{ site.baseurl }}installing/email) - - |