diff options
Diffstat (limited to 'docs/installing')
| -rw-r--r-- | docs/installing/ami.md | 2 | ||||
| -rw-r--r-- | docs/installing/deploy.md | 15 | ||||
| -rw-r--r-- | docs/installing/index.md | 19 | ||||
| -rw-r--r-- | docs/installing/manual_install.md | 104 | ||||
| -rw-r--r-- | docs/installing/script.md | 2 |
5 files changed, 105 insertions, 37 deletions
diff --git a/docs/installing/ami.md b/docs/installing/ami.md index 1f7195761..e63e70023 100644 --- a/docs/installing/ami.md +++ b/docs/installing/ami.md @@ -1,6 +1,6 @@ --- layout: page -title: Installing the easy way +title: Installation from AMI --- # Installation on Amazon EC2 diff --git a/docs/installing/deploy.md b/docs/installing/deploy.md index 0e4f6c4ad..5795f1a22 100644 --- a/docs/installing/deploy.md +++ b/docs/installing/deploy.md @@ -8,7 +8,8 @@ title: Deploying <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 }}docs/glossary/#production">production server</a>. + especially on your + <a href="{{ site.baseurl }}docs/glossary/#production" class="glossary__link">production server</a>. Alaveteli provides a deployment mechanism using Capistrano. </p> @@ -27,13 +28,13 @@ 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 }}docs/glossary/#production">production server</a> and, if -you're running one, your -<a href="{{ site.baseurl }}docs/glossary/#staging">staging server</a> too. +<a href="{{ site.baseurl }}docs/glossary/#production" class="glossary__link">production server</a> +and, if you're running one, your +<a href="{{ site.baseurl }}docs/glossary/#staging" class="glossary__link">staging server</a> too. ## Capistrano -<a href="{{site.baseurl}}docs/glossary/#capistrano" class="glossary">Capistrano</a> +<a href="{{site.baseurl}}docs/glossary/#capistrano" class="glossary__link">Capistrano</a> is included as part of Alaveteli as a standard deployment system. The basic principle of Capistrano is that you execute `cap [do-something]` @@ -116,8 +117,8 @@ 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 <a href="{{site.baseurl}}docs/glossary/#staging" class="glossary">staging site</a>, or... - * `cap -S stage=production deploy` for <a href="{{site.baseurl}}docs/glossary/#production" class="glossary">production</a> + * `cap deploy` if you're deploying a <a href="{{site.baseurl}}docs/glossary/#staging" class="glossary__link">staging site</a>, or... + * `cap -S stage=production deploy` for <a href="{{site.baseurl}}docs/glossary/#production" class="glossary__link">production</a> * 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 diff --git a/docs/installing/index.md b/docs/installing/index.md index c276c3d08..50bcfd25a 100644 --- a/docs/installing/index.md +++ b/docs/installing/index.md @@ -6,17 +6,19 @@ title: Installing # Installing 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. - This has several advantages, especially for your - <a href="{{ site.baseurl }}docs/glossary/#production">production server</a>. + 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, or you can follow the manual + installation instructions. </p> ## Before you start This is important: you need to decide if you are installing Alaveteli for -[development]({{ site.baseurl }}docs/glossary/#development) or -[production]({{ site.baseurl }}docs/glossary/#production). +<a href="{{ site.baseurl }}docs/glossary/#development" class="glossary__link">development</a> or +<a href="{{ site.baseurl }}docs/glossary/#production" class="glossary__link">production</a>. 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 @@ -30,9 +32,10 @@ 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 }}docs/installing/deploy/) too. -Ideally, you should also have a [staging site]({{ site.baseurl }}docs/glossary/#staging), +Ideally, you should also have a +<a href="{{ site.baseurl }}docs/glossary/#staging" class="glossary__link">staging site</a>, which is used solely to test new code in an identical environment to your -production site but before it goes live. +production site 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 diff --git a/docs/installing/manual_install.md b/docs/installing/manual_install.md index 0c53fa91b..821188b85 100644 --- a/docs/installing/manual_install.md +++ b/docs/installing/manual_install.md @@ -19,15 +19,15 @@ Note that there are [other ways to install Alaveteli]({{ site.baseurl }}docs/ins ## Target operating system -These instructions assume Debian Squeeze (64-bit) or Ubuntu 12.04 LTS -(precise). Debian Squeeze is the best supported deployment platform. We also +These instructions assume Debian Wheezy or Squeeze (64-bit) or Ubuntu 12.04 LTS +(precise). Debian is the best supported deployment platform. We also have instructions for [installing on MacOS]({{ site.baseurl }}docs/installing/macos/). Commands are intended to be run via the terminal or over ssh. ## Set the locale -**Debian Squeeze** +**Debian Wheezy or Squeeze** Follow the [Debian guide](https://wiki.debian.org/Locale#Standard) for configuring the locale of the operating system. @@ -60,59 +60,118 @@ submodules, run: git submodule update --init -## Install system dependencies +## Prepare to install system dependencies using OS packages These are packages that the software depends on: third-party software used to parse documents, host the site, and so on. There are also packages that contain headers necessary to compile some of the gem dependencies in the next step. +<div class="attention-box"> +Note the commands in this section will require root privileges +</div> + +### Using other repositories to get more recent packages + Add the following repositories to `/etc/apt/sources.list`: **Debian Squeeze** - cat > /etc/apt/sources.list.d/debian-backports.list <<EOF + cat > /etc/apt/sources.list.d/debian-extra.list <<EOF deb http://backports.debian.org/debian-backports squeeze-backports main contrib non-free + deb http://the.earth.li/debian/ wheezy main contrib non-free + EOF + +The squeeze-backports repository is providing a more recent version of rubygems, and the wheezy repository is providing bundler. You should configure package-pinning to reduce the priority of the wheezy repository so other packages aren't pulled from it. + + cat >> /etc/apt/preferences <<EOF + + Package: bundler + Pin: release n=wheezy + Pin-Priority: 990 + + Package: * + Pin: release n=wheezy + Pin-Priority: 50 EOF -The repositories above let you install `wkhtmltopdf-static` and `bundler` using -`apt`. +**Debian Wheezy** + + cat > /etc/apt/sources.list.d/debian-extra.list <<EOF + # Debian mirror to use, including contrib and non-free: + deb http://the.earth.li/debian/ wheezy main contrib non-free + deb-src http://the.earth.li/debian/ wheezy main contrib non-free + + # Security Updates: + deb http://security.debian.org/ wheezy/updates main non-free + deb-src http://security.debian.org/ wheezy/updates main non-free + EOF **Ubuntu Precise** cat > /etc/apt/sources.list.d/ubuntu-extra.list <<EOF - deb http://eu-west-1.ec2.archive.ubuntu.com/ubuntu/ precise multiverse - deb-src http://eu-west-1.ec2.archive.ubuntu.com/ubuntu/ precise multiverse - deb http://eu-west-1.ec2.archive.ubuntu.com/ubuntu/ precise-updates multiverse - deb-src http://eu-west-1.ec2.archive.ubuntu.com/ubuntu/ precise-updates multiverse + deb http://de.archive.ubuntu.com/ubuntu/ precise multiverse + deb-src http://de.archive.ubuntu.com/ubuntu/ precise multiverse + deb http://de.archive.ubuntu.com/ubuntu/ precise-updates multiverse + deb-src http://de.archive.ubuntu.com/ubuntu/ precise-updates multiverse + deb http://de.archive.ubuntu.com/ubuntu/ raring universe + deb-src http://de.archive.ubuntu.com/ubuntu/ raring universe + EOF + +The raring repo is used here to get a more recent version of bundler and pdftk. You should configure package-pinning to reduce the priority of the raring repository so other packages aren't pulled from it. + + cat >> /etc/apt/preferences <<EOF + + Package: ruby-bundler + Pin: release n=raring + Pin-Priority: 990 + + Package: pdftk + Pin: release n=raring + Pin-Priority: 990 + + Package: * + Pin: release n=raring + Pin-Priority: 50 EOF -The repositories above let you install `wkhtmltopdf-static` using `apt`. -`bundler` will have to be installed manually on Ubuntu Precise. ### Packages customised by mySociety -If you're using Debian, you should add the mySociety Debian archive to your +If you're using Debian or Ubuntu, you should add the mySociety Debian archive to your apt sources. Note that mySociety packages are currently only built for 64-bit Debian. +**Debian Squeeze, Wheezy or Ubuntu Precise** + cat > /etc/apt/sources.list.d/mysociety-debian.list <<EOF deb http://debian.mysociety.org squeeze main EOF +The repository above lets you install `wkhtmltopdf-static` and `pdftk` (for squeeze) using `apt`. + Add the GPG key from the [mySociety Debian Package Repository](http://debian.mysociety.org/). wget -O - https://debian.mysociety.org/debian.mysociety.org.gpg.key | sudo apt-key add - + +**Debian Wheezy or Ubuntu Precise** + You should also configure package-pinning to reduce the priority of this -repository. +repository - we only want to pull wkhtmltopdf-static from mysociety. + + cat >> /etc/apt/preferences <<EOF - cat > /etc/apt/preferences <<EOF Package: * Pin: origin debian.mysociety.org Pin-Priority: 50 EOF -If you're using some other platform, you can optionally install these +**Debian Squeeze** + +No special package pinning is required. + +### Other platforms +If you're using some other linux platform, you can optionally install these dependencies manually, as follows: 1. If you would like users to be able to get pretty PDFs as part of the @@ -126,13 +185,15 @@ everything will still work, but users will get ugly, plain text versions of their requests when they download them. 2. Version 1.44 of `pdftk` contains a bug which makes it loop forever in -certain edge conditions. Until it's incorporated into an official release, you +certain edge conditions. This is fixed in the standard 1.44.7 package which is available in wheezy (Debian) and raring (Ubuntu). + +If you can't get an official release for your OS with the fix, you can either hope you don't encounter the bug (it ties up a rails process until you kill it), patch it yourself, or use the Debian package compiled by mySociety (see link in [issue 305](https://github.com/mysociety/alaveteli/issues/305)) -### Install the dependencies +## Install the dependencies Refresh the sources after adding the extra repositories: @@ -140,6 +201,9 @@ Refresh the sources after adding the extra repositories: Now install the packages relevant to your system: + # Debian Wheezy + sudo apt-get install $(cat config/packages.debian-wheezy) + # Debian Squeeze sudo apt-get install $(cat config/packages.debian-squeeze) @@ -153,7 +217,7 @@ choice of packages. ## Install Ruby dependencies To install Alaveteli's Ruby dependencies, you need to install bundler. In -Debian, this is provided as a package (installed as part of the package install +Debian and Ubuntu, this is provided as a package (installed as part of the package install process above). You could also install it as a gem: sudo gem install bundler diff --git a/docs/installing/script.md b/docs/installing/script.md index b8b678a0a..0d826ac8a 100644 --- a/docs/installing/script.md +++ b/docs/installing/script.md @@ -1,6 +1,6 @@ --- layout: page -title: Installing the easy way +title: Installation script --- # Installation script |