diff options
Diffstat (limited to 'docs/installing/manual_install.md')
| -rw-r--r-- | docs/installing/manual_install.md | 206 |
1 files changed, 154 insertions, 52 deletions
diff --git a/docs/installing/manual_install.md b/docs/installing/manual_install.md index 841617477..7eac53ae3 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 a 64-bit version of Debian 6 (Wheezy), Debian 7 (Squeeze) +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 repositories above let you install `wkhtmltopdf-static` and `bundler` using -`apt`. +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 + +**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 @@ -341,56 +405,90 @@ site in action. ## Cron jobs and init scripts -`config/crontab-example` contains the cronjobs run on WhatDoTheyKnow. It's in a -strange templating format they use in mySociety. mySociety render the example -file to reference absolute paths, and then drop it in `/etc/cron.d/` on the -server. +The crontab and init scripts use the `.ugly` file format, which is a strange +templating format used by mySociety. The `ugly` format uses simple variable substitution. A variable looks like -`!!(*= $this *)!!`. The variables are: - -* `vhost`: part of the path to the directory where the software is - served from. In the mySociety files, it usually comes as - `/data/vhost/!!(*= $vhost *)!!` -- you should replace that whole - port with a path to the directory where your Alaveteli software - installation lives, e.g. `/var/www/` -* `vhost_dir`: the entire path to the directory where the software is - served from. -- you should replace this with a path to the - directory where your Alaveteli software installation lives, - e.g. `/var/www/` -* `vcspath`: the name of the alaveteli checkout, e.g. `alaveteli`. - Thus, `/data/vhost/!!(*= $vhost *)!!/!!(*= $vcspath *)!!` might be - replaced with `/var/www/alaveteli` in your cron tab +`!!(*= $this *)!!`. + +### Generate crontab + +`config/crontab-example` contains the cron jobs that run on +WhatDoTheyKnow. mySociety render the example file to reference absolute paths, +and then drop it in `/etc/cron.d/` on the server. + +**Template Variables:** + +* `vhost_dir`: the full path to the directory where alaveteli is checked out. + e.g. If your checkout is at `/var/www/alaveteli` then set this to `/var/www` +* `vcspath`: the name of the directory that contains the alaveteli code. + e.g. `alaveteli` * `user`: the user that the software runs as * `site`: a string to identify your alaveteli instance +* `mailto`: The email address that cron output will be sent to There is a rake task that will help to rewrite this file into one that is -useful to you, which can be invoked with: +useful to you. Change the variables to suit your installation. bundle exec rake config_files:convert_crontab \ DEPLOY_USER=deploy \ - VHOST_DIR=/dir/above/alaveteli \ - VCSPATH=alaveteli \ - SITE=alaveteli \ - CRONTAB=config/crontab-example > crontab + VHOST_DIR=/var/www \ + VCSPATH=alaveteli \ + SITE=alaveteli \ + MAILTO=cron-alaveteli@example.org \ + CRONTAB=config/crontab-example > /etc/cron.d/alaveteli -You should change the `DEPLOY_USER`, `VHOST_DIR`, `VCSPATH` and `SITE` -environment variables to match your server and installation. You should also -edit the resulting `crontab` file to customize the `MAILTO` variable. +### Generate alert daemon One of the cron jobs refers to a script at `/etc/init.d/foi-alert-tracks`. This -is an init script, a copy of which lives in `config/alert-tracks-debian.ugly`. -As with the cron jobs above, replace the variables (and/or bits near the -variables) with paths to your software. You can use the rake task `rake -config_files:convert_init_script` to do this. +is an init script, which can be generated from the +`config/alert-tracks-debian.ugly` template. + +**Template Variables:** + +* `vhost_dir`: the full path to the directory where alaveteli is checked out. + e.g. If your checkout is at `/var/www/alaveteli` then set this to `/var/www` +* `user`: the user that the software runs as + +There is a rake task that will help to rewrite this file into one that is +useful to you. Change the variables to suit your installation. + + bundle exec rake config_files:convert_init_script \ + DEPLOY_USER=deploy \ + VHOST_DIR=/var/www \ + SCRIPT_FILE=config/alert-tracks-debian.ugly > /etc/init.d/foi-alert-tracks + +### Generate varnish purge daemon `config/purge-varnish-debian.ugly` is a similar init script, which is optional and not required if you choose not to run your site behind Varnish (see below). + +**Template Variables:** + +* `daemon_name`: The name of the daemon. Set this to `purge-varnish`. +* `vhost_dir`: the full path to the directory where alaveteli is checked out. + e.g. If your checkout is at `/var/www/alaveteli` then set this to `/var/www` +* `user`: the user that the software runs as + +This template does not yet have a rake task to generate it. + +### Init script permissions + Either tweak the file permissions to make the scripts executable by your deploy user, or add the following line to your sudoers file to allow these to be run -by your deploy user (named `deploy` in this case): +by your deploy user (named `deploy` in this case). - deploy ALL = NOPASSWD: /etc/init.d/foi-alert-tracks, /etc/init.d/foi-purge-varnish + deploy ALL = NOPASSWD: /etc/init.d/foi-alert-tracks, /etc/init.d/foi-purge-varnish + +There is also an example config for stopping and starting the +Alaveteli app server as a service in `config/sysvinit.example`. This +example assumes you're using Thin as an application server, so will +need tweaking for Passenger or any other app server. You can install +this by copying it to `/etc/init.d/alaveteli` and setting the +`SITE_HOME` variable to the path where Alaveteli is running, and the +`USER` variable to the Unix user that will be running Alaveteli. Once +that's done, you can restart Alaveteli with `/etc/init.d/alaveteli +restart`. ## Set up production web server @@ -443,6 +541,10 @@ and so it knows to include that in any absolute urls it serves. We have some [production server best practice notes]({{ site.baseurl}}docs/running/server/). +## What next? + +Check out the [next steps]({{ site.baseurl }}docs/installing/next_steps/). + ## Troubleshooting * **Incoming emails aren't appearing in my Alaveteli install** |