From 02e9e6bb5f7fc73d30cbf8af5952be774d34cf3e Mon Sep 17 00:00:00 2001 From: Dave Whiteland Date: Tue, 10 Jun 2014 12:52:31 +0100 Subject: add deployment to docs, update install pages accordingly Also added glossary entries for dev/staging/production. The deployment text is from doc/DEPLOY.md which will can be removed if this goes live into code.alaveteli.org --- installing/deploy.md | 78 ++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 78 insertions(+) create mode 100644 installing/deploy.md (limited to 'installing/deploy.md') 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 + +

+ Although you can install Alaveteli and just change it when you need it, we + recommend you adopt a way of deploying it automatically, + especially on your production server. + Alaveteli provides a deployment mechanism using Capistrano. +

+ +## 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 +production server and, if +you're running one, your +staging server 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/). + -- cgit v1.2.3 From 4f0c0cb5a1593b885569d80ab3651786929056b8 Mon Sep 17 00:00:00 2001 From: Dave Whiteland Date: Thu, 12 Jun 2014 09:09:13 +0100 Subject: clarifications to deploy page --- installing/deploy.md | 54 ++++++++++++++++++++++++++++++++++------------------ 1 file changed, 35 insertions(+), 19 deletions(-) (limited to 'installing/deploy.md') diff --git a/installing/deploy.md b/installing/deploy.md index 49e960a32..63be3c96d 100644 --- a/installing/deploy.md +++ b/installing/deploy.md @@ -37,41 +37,57 @@ 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. +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 local machine. -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): +* your *local machine* may be your laptop or similar device -- as well as those + belonging to anyone in your team whom you want to be able to deploy +* *the server* is the machine (possibly on that will be running the Alaveteli instance you're deploying + +First you need to customise the deployment settings on your own machine. Copy +the example file `config/deploy.yml.example` to `config/deploy.yml` and edit +the settings to suit -- for example, the name of the server. + +These are the general steps required to set up the deployment mechanism: + +On your local machine: * 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 +* Run `cap deploy:update_code` so that there's a copy of the example config on the server. + This process will take a long time installing gems and suchlike. + It will also fail on `rake:themes:install` -- but that's OK + +Next, on the server: + +> *Note:* if you've *already* installed Alaveteli, these files may already be in place. +> Otherwise, you should [install Alaveteli]({{ site.baseurl }}installing/) first. + +* 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` + +Then, back on your local machine: + +* Back on your machine, run `cap deploy` and it should successfully deploy +* Do the DB migrations: run `cap deploy:migrate` +* Build the Xapian database: run `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/). +site. If there are other people in your team who need to deploy, you'll need to +share it with them too -- 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`. +* to deploy to staging, just run `cap deploy` +* to deploy to production, run `cap -S stage=production deploy` For additional usage instructions, see the [Capistrano wiki](https://github.com/capistrano/capistrano/wiki/). -- cgit v1.2.3 From 9d6ff9e88126a65f4763d9145beb82b5363c7472 Mon Sep 17 00:00:00 2001 From: Dave Whiteland Date: Thu, 12 Jun 2014 09:16:38 +0100 Subject: explicit link to installation from deploy page --- installing/deploy.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) (limited to 'installing/deploy.md') diff --git a/installing/deploy.md b/installing/deploy.md index 63be3c96d..d0d548a64 100644 --- a/installing/deploy.md +++ b/installing/deploy.md @@ -14,9 +14,9 @@ title: Deploying ## 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. +Although you can [install Alaveteli]({{ site.baseurl }}installing/) 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 -- cgit v1.2.3 From fdf2e096d227c3239efb6b182cb668ac4a23db31 Mon Sep 17 00:00:00 2001 From: Dave Whiteland Date: Thu, 12 Jun 2014 09:51:56 +0100 Subject: add Capistrano to the glossary --- installing/deploy.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) (limited to 'installing/deploy.md') diff --git a/installing/deploy.md b/installing/deploy.md index d0d548a64..acaf00e3b 100644 --- a/installing/deploy.md +++ b/installing/deploy.md @@ -33,7 +33,8 @@ you're running one, your ## Capistrano -Capistrano is included as part of Alaveteli as a standard deployment system. +Capistrano +is included as part of Alaveteli as a standard deployment system. ### Set up -- cgit v1.2.3 From 0b703b25e7088400f0522d3c3b72a585140466c4 Mon Sep 17 00:00:00 2001 From: Dave Whiteland Date: Fri, 13 Jun 2014 14:15:54 +0100 Subject: fixes to comments/input from @crowbot This includes the deploy/Capistrano instructions from #1596 --- installing/deploy.md | 144 ++++++++++++++++++++++++++++++++++++++------------- 1 file changed, 108 insertions(+), 36 deletions(-) (limited to 'installing/deploy.md') diff --git a/installing/deploy.md b/installing/deploy.md index acaf00e3b..32755a71d 100644 --- a/installing/deploy.md +++ b/installing/deploy.md @@ -36,52 +36,113 @@ you're running one, your Capistrano is included as part of Alaveteli as a standard deployment system. +The basic principle of Capistrano is that you execute `cap [do-something]` +commands on your local machine, and Capistrano connects to your server (using +`ssh`) and does the corresponding task there for you. + ### Set up 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 local machine. +* *the server* is the machine that will be running the Alaveteli + instance you're deploying + * your *local machine* may be your laptop or similar device -- as well as those belonging to anyone in your team whom you want to be able to deploy -* *the server* is the machine (possibly on that will be running the Alaveteli instance you're deploying - -First you need to customise the deployment settings on your own machine. Copy -the example file `config/deploy.yml.example` to `config/deploy.yml` and edit -the settings to suit -- for example, the name of the server. - -These are the general steps required to set up the deployment mechanism: - -On your local machine: - -* 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 there's a copy of the example config on the server. - This process will take a long time installing gems and suchlike. - It will also fail on `rake:themes:install` -- but that's OK - -Next, on the server: - -> *Note:* if you've *already* installed Alaveteli, these files may already be in place. -> Otherwise, you should [install Alaveteli]({{ site.baseurl }}installing/) first. - -* 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 - -Then, back on your local machine: - -* Back on your machine, run `cap deploy` and it should successfully deploy -* Do the DB migrations: run `cap deploy:migrate` -* Build the Xapian database: run `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! +In order to allow the Capistrano deployment mechanism work, you need to set up +the server so that the Alaveteli app is being served from a directory called +`current`. Once you've done that, deploying a new version is essentially +creating a timestamped sister directory to the `current` directory, and +switching the symlink `current` from the old timestamped directory to the new +one. Things that need to persist between deployments, like config files, are +kept in a `shared` directory that is at the same level, and symlinked-to from +each timestamped deploy directory. + +We're [working on making this easier](https://github.com/mysociety/alaveteli/issues/1596), +but for now, here's the manual process you need to follow to set up this +deployment mechanism. Remember, you only have to do this once to set it up, +and thereafter you'll be able to deploy very easily (see [usage, below](#usage)). + +First, on the server: + +* [install Alaveteli]({{ site.baseurl }}installing/) +* then move the Alaveteli app to a temporary place on the server, like your home + directory (temporarily, your site will be missing, until the deployment puts + new files in place) + +Next, on your local machine: + +* install Capistrano: + * Capistrano requires Ruby 1.9 or more, and can be installed using rubygems + * do: `gem install capistrano` +* install Bundler if you don't have it already -- do: `gem install bundler` +* checkout the [Alaveteli repo](http://github.com/mysociety/alaveteli/) (you + need some of the files available locally even though you might not be running + Alaveteli on this machine) +* copy the example file `config/deploy.yml.example` to `config/deploy.yml` +* now customise the deployment settings in that file: edit `config/deploy.yml` + appropriately -- for example, edit the name of the server. Also, change + `deploy_to` to be the path where Alaveteli is currently installed on the + server -- if you used the installation script, this will be + `/var/www/alaveteli/alaveteli`. +* `cd` into the Alaveteli repo you checked out (otherwise the `cap` commands you're about to + execute won't work) +* still on your local machine, run `cap -S stage=staging deploy:setup` to setup capistrano on the server +* again on your local machine, run `cap -S stage=staging deploy:update_code` to get a code checkout on the server + +Back on the server: + +* copy the following config files from the temporary copy of Alaveteli you made at + the begining (perhaps in your home directory) to the `shared` directory that + Capistrano just created on the server: + * `general.yml` + * `database.yml` + * `rails_env.rb` + * `newrelic.yml` + * `aliases` ← if you're using Exim as your MTA +* if you're using Exim as your MTA, edit the `aliases` file you just copied across + so that the path to Alaveteli includes the `current` element. If it was + `/var/www/alaveteli/alaveteli/script/mailin`, it should now be + `/var/www/alaveteli/alaveteli/current/script/mailin`. +* copy the following directories from your temporary copy of Alaveteli to the + `shared` directory created by Capistrano on the server: + * `cache/` + * `files/` + +Now, back on your local machine: + +* make sure you're still in the Alaveteli repo (if not, `cd` back into it) +* create a deployment directory on the server by running *one* of these commands: + * `cap deploy` if you're deploying a staging site, or... + * `cap -S stage=production deploy` for production +* update the webserver config (either apache or nginx) to add the `current` element + to the path where it is serving Alaveteli from. If you installed using the + installation script, this will be replacing `/var/www/alaveteli/alaveteli/` with + `/var/www/alaveteli/alaveteli/current` in `etc/nginx/sites-available/default`. +* edit the server crontab so that the paths in the cron jobs also include the + `current` element. If you used the installation script the crontab will be in + `etc/cron.d/alaveteli`. +* Update the MTA config to include the `current` element in the paths it uses. + If you installed using the installation script, the MTA will be postfix, + and you will need to edit `/etc/postfix/master.cf` to replace + `argv=/var/www/alaveteli/alaveteli/script/mailin` with + `argv=/var/www/alaveteli/alaveteli/current/script/mailin`. + If you're using Exim as your MTA, edit `etc/exim4/conf.d/04_alaveteli_options` + to update the `ALAVETELI_HOME` variable to the new Alaveteli path. + +Phew, you're done! + +You can delete the temporary copy of Alaveteli (perhaps in your +home directory) now. ### Usage +Before you issue any Capistrano commands, `cd` into the checkout of the +Alaveteli repo on your local machine (because that's where it will look +for the config that you've set up). + Ensure you've got a `config/deploy.yml` file with the correct settings for your site. If there are other people in your team who need to deploy, you'll need to share it with them too -- it might be a good idea to keep the latest @@ -90,6 +151,17 @@ version in a [Gist](http://gist.github.com/). * to deploy to staging, just run `cap deploy` * to deploy to production, run `cap -S stage=production deploy` +You might notice that, after deploying, the old deploy directory is still there +-- that is, the one that was `current` until you replaced it with the new one. +By default, the deploy mechanism keeps the last five deployments there. Run +`cap deploy:cleanup` to tidy up older versions. + For additional usage instructions, see the [Capistrano -wiki](https://github.com/capistrano/capistrano/wiki/). +website](http://capistranorb.com/). + +### Whoops, that's not what I expected + +If a deployment goes wrong, or you discover after doing it that you're not +ready for the latest version after all, don't panic! Run `cap deploy:rollback` +and it will switch `current` back to the previous deployment. -- cgit v1.2.3