aboutsummaryrefslogtreecommitdiffstats
path: root/docs/installing
diff options
context:
space:
mode:
Diffstat (limited to 'docs/installing')
-rw-r--r--docs/installing/ami.md17
-rw-r--r--docs/installing/deploy.md62
-rw-r--r--docs/installing/index.md24
-rw-r--r--docs/installing/manual_install.md206
-rw-r--r--docs/installing/next_steps.md34
-rw-r--r--docs/installing/script.md24
-rw-r--r--docs/installing/vagrant.md70
7 files changed, 345 insertions, 92 deletions
diff --git a/docs/installing/ami.md b/docs/installing/ami.md
index 1f7195761..cee4f88af 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
@@ -13,11 +13,13 @@ Note that there are [other ways to install Alaveteli]({{ site.baseurl }}docs/ins
## Installing from our AMI
-To help people try out Alaveteli, we have created an AMI (Amazon Machine Image)
-with a basic installation of Alaveteli, which you can use to create a running
-server on an Amazon EC2 instance. This creates an instance that runs in
-development mode, so we wouldn't recommend you use it for a production system
-without changing the configuration.
+To help people try out Alaveteli, we have created an AMI (Amazon Machine
+Image) with a basic installation of Alaveteli (installed using the
+[installation script]({{ site.baseurl }}docs/installing/script/)), which
+you can use to create a running server on an Amazon EC2 instance. This
+creates an instance that runs in development mode, so we wouldn't
+recommend you use it for a production system without changing the
+configuration.
Unfortunately, Alaveteli will not run properly on a free Micro
instance due to the low amount of memory available on those
@@ -57,3 +59,6 @@ If you have any problems or questions, please ask on the [Alaveteli Google
Group](https://groups.google.com/forum/#!forum/alaveteli-dev) or [report an
issue](https://github.com/mysociety/alaveteli/issues?state=open).
+##What next?
+
+Check out the [next steps]({{ site.baseurl }}docs/installing/next_steps/).
diff --git a/docs/installing/deploy.md b/docs/installing/deploy.md
index 4bbc91a9d..64ecde088 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]`
@@ -68,7 +69,11 @@ and thereafter you'll be able to deploy very easily (see [usage, below](#usage))
First, on the server:
* [install Alaveteli]({{ site.baseurl }}docs/installing/)
-* then move the Alaveteli app to a temporary place on the server, like your home
+* give the Unix user that runs Alaveteli the ability to ssh to your server. Either give them a password or, preferably, set up ssh keys for them so they can ssh from your local machine to the server:
+ * to give them a password (if they don't already have one) - `sudo passwd [UNIX-USER]`. Store this password securely on your local machine e.g in a password manager
+ * to set up ssh keys for them, follow the instructions in the [capistrano documentation](http://capistranorb.com/documentation/getting-started/authentication-and-authorisation/). There's no need to set up ssh keys to the git repository as it is public.
+* make sure the Unix user that runs Alaveteli has write permissions on the parent directory of your Alaveteli app
+* 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)
@@ -82,20 +87,31 @@ Next, on your local machine:
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`.
+* 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/[HOST or alaveteli]/alaveteli`. If
+ you're running the thin application server rather than passenger,
+ you'll need to set `rails_app_server` to `thin` and `rails_app_port`
+ to whatever port it's running on. If you installed with the install
+ script, this will be port 3300.
+
+
* `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
+
+If you get an error `SSH::AuthenticationFailed`, and are not prompted for the password of the deployment user, you may have run into [a bug](http://stackoverflow.com/questions/21560297/capistrano-sshauthenticationfailed-not-prompting-for-password) in the net-ssh gem version 2.8.0. Try installing version 2.7.0 instead:
+
+ gem uninstall net-ssh
+
+ gem install net-ssh -v 2.7.0
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
+ the beginning (perhaps in your home directory) to the `shared` directory that
Capistrano just created on the server:
* `general.yml`
* `database.yml`
@@ -110,17 +126,23 @@ Back on the server:
`shared` directory created by Capistrano on the server:
* `cache/`
* `files/`
+ * `lib/acts_as_xapian/xapiandbs` (copy this to straight into `shared` so it becomes `shared/xapiandbs`)
+ * `log/`
Now, back on your local machine:
* make sure you're still in the Alaveteli repo (if not, `cd` back into it)
+* run `cap -S stage=staging deploy:update_code` to get a code checkout on the server.
* 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>
+
+Back on the server:
+
* 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`.
+ `/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`.
@@ -130,7 +152,13 @@ Now, back on your local machine:
`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.
+ to update the `ALAVETELI_HOME` variable to the new Alaveteli path. Restart the MTA after you've made these changes.
+
+* You will also need to update the path to Alaveteli in your [init scripts]({{site.baseurl}}docs/installing/manual_install/#cron-jobs-and-init-scripts).
+ You should have a script for running the alert tracks
+ (`/etc/init.d/foi-alert-tracks`), and possibly scripts for purging the
+ varnish cache (`/etc/init.d/foi-purge-varnish`), and restarting the
+ app server (`/etc/init.d/alaveteli`).
Phew, you're done!
diff --git a/docs/installing/index.md b/docs/installing/index.md
index c276c3d08..c04aaa3ca 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
@@ -47,6 +50,7 @@ those servers, because Capistrano takes care of that for you.
## Installing the core code
+* [Install into a Vagrant virtual development environment]({{ site.baseurl }}docs/installing/vagrant/) -- a good choice for development, and playing around with the site.
* [Install on Amazon EC2]({{ site.baseurl }}docs/installing/ami/) using our AMI
* [Use the installation script]({{ site.baseurl }}docs/installing/script/) which does the full installation on your own server
* [Manual installation]({{ site.baseurl }}docs/installing/manual_install/) -- step-by-step instructions
@@ -56,7 +60,7 @@ If you're setting up a development server on MacOS X, we've also got
## 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. If you're installing manually, you need to [setup your
+MTA (Mail Transfer Agent) appropriately]({{ site.baseurl }}docs/installing/email/). The other install methods will do this for you.
* [Installing the MTA]({{ site.baseurl }}docs/installing/email/)
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**
diff --git a/docs/installing/next_steps.md b/docs/installing/next_steps.md
new file mode 100644
index 000000000..98a661416
--- /dev/null
+++ b/docs/installing/next_steps.md
@@ -0,0 +1,34 @@
+---
+layout: page
+title: Next Steps
+---
+# Next Steps
+
+<p class="lead">
+ OK, you've installed a copy of Alaveteli, and can see the site in a browser. What next?
+</p>
+
+
+### Create a superuser account for yourself
+
+* Sign up for a new account on the site. You should receive a confirmation email. Click on the link in it to confirm the account.
+
+* Get access to the [admin interface]({{ site.baseurl}}docs/running/admin_manual/#administrator-privileges). You can find the
+`general.yml` file you'll need to get the `ADMIN_USERNAME` and
+`ADMIN_PASSWORD` credentials in the `config` subdirectory of the
+directory Alaveteli was installed into.
+
+* In the admin interface, go to the 'Users' section and find the account you just created. Promote the account you just created to superuser status by clicking the 'Edit' button and setting the 'Admin level' value to 'super'.
+
+### Test out the request process
+
+* Create a new public authority in the admin interface - give it a name something like 'Test authority'. Set the request email to an address that you will receive.
+
+* From the main interface of the site, make a request to the new authority.
+
+* You should receive the request email - try replying to it. Your response email should appear in Alaveteli. Not working? Take a look at our [troubleshooting tips]({{ site.baseurl}}docs/installing/manual_install/#troubleshooting). If that doesn't sort it out, [get in touch]({{ site.baseurl}}community/) on the project mailing list or IRC
+for help.
+
+### Start thinking about customising Alaveteli
+
+Check out [our guide]({{ site.baseurl}}docs/customising/).
diff --git a/docs/installing/script.md b/docs/installing/script.md
index b8b678a0a..72fbd6438 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
@@ -16,7 +16,7 @@ Note that there are [other ways to install Alaveteli]({{ site.baseurl }}docs/ins
If you have a clean installation of Debian squeeze 64-bit or Ubuntu precise, you can
use an install script in our commonlib repository to set up a working instance
of Alaveteli. This is not suitable for production (it runs in development mode,
-for example) but should set up a functional installation of the site.
+for example) but should set up a functional installation of the site, which can send and receive email.
**Warning: only use this script on a newly installed server – it will make
significant changes to your server’s setup, including modifying your nginx
@@ -25,7 +25,7 @@ etc.**
To download the script, run the following command:
- curl -O https://raw.github.com/mysociety/commonlib/master/bin/install-site.sh
+ curl -O https://raw.githubusercontent.com/mysociety/commonlib/master/bin/install-site.sh
If you run this script with `sh install-site.sh`, you'll see its usage message:
@@ -56,10 +56,20 @@ could download the script, make it executable and then invoke it with:
sudo ./install-site.sh --default alaveteli alaveteli
+If you have any problems or questions, please ask on the [Alaveteli Google
+ Group](https://groups.google.com/forum/#!forum/alaveteli-dev) or [report an
+ issue](https://github.com/mysociety/alaveteli/issues?state=open).
+
+## What the install script does
+
When the script has finished, you should have a working copy of the website,
-accessible via the hostname you supplied to the script.
+accessible via the hostname you supplied to the script. So, for this example, you could access the site in a browser at `http://alaveteli.10.10.10.30.xip.io`. The site runs using the thin application server, and the nginx webserver. By default, Alaveteli will be installed into `/var/www/[HOST]` on the server.
+
+The server will also be configured to accept replies to information request emails (as long as the MX record for the domain is pointing at the server). Incoming mail handling is set up using Postfix as the MTA.
+
+##What next?
+
+Check out the [next steps]({{ site.baseurl }}docs/installing/next_steps/).
+
-If you have any problems or questions, please ask on the [Alaveteli Google
-Group](https://groups.google.com/forum/#!forum/alaveteli-dev) or [report an
-issue](https://github.com/mysociety/alaveteli/issues?state=open).
diff --git a/docs/installing/vagrant.md b/docs/installing/vagrant.md
new file mode 100644
index 000000000..8938d496b
--- /dev/null
+++ b/docs/installing/vagrant.md
@@ -0,0 +1,70 @@
+---
+layout: page
+title: Vagrant
+---
+# Alaveteli using Vagrant
+
+<p class="lead">
+Vagrant provides an easy method to set up virtual development environments; for
+further information see <a href="http://www.vagrantup.com">the Vagrant website</a>.
+We bundle an example Vagrantfile in the repository, which runs the
+<a href="{{ site.baseurl }}docs/installing/script/">install script</a> for you.
+</p>
+
+Note that this is just one of [several ways to install Alaveteli]({{ site.baseurl }}docs/installing/).
+
+The included steps will use vagrant to create a development environment
+where you can run the test suite, the development server and make
+changes to the codebase.
+
+The basic process is to create a base virtual machine, and then
+provision it with the software packages and setup needed. The supplied
+scripts will create you a Vagrant VM based on the server edition of
+Ubuntu 12.04 LTS that contains everything you need to work on Alaveteli.
+
+1. Get a copy of Alaveteli from GitHub and create the Vagrant instance.
+ This will provision the system and can take some time - usually at
+ least 20 minutes.
+
+ # on your machine
+ $ git clone git@github.com:mysociety/alaveteli.git
+ $ cd alaveteli
+ $ git submodule update --init
+ $ vagrant --no-color up
+
+2. You should now be able to ssh in to the Vagrant guest OS and run the
+ test suite:
+
+ $ vagrant ssh
+
+ # You are now in a terminal on the virtual machine
+ $ cd /home/vagrant/alaveteli
+ $ bundle exec rake spec
+
+
+3. Run the rails server and visit the application in your host browser
+ at http://10.10.10.30:3000
+
+ # in the virtual machine terminal
+ bundle exec rails server
+
+## What next?
+
+Check out the [next steps]({{ site.baseurl }}docs/installing/next_steps/).
+
+## Customizing the Vagrant instance
+
+The Vagrantfile allows customisation of some aspects of the virtual machine. See the customization options in the file [`Vagrantfile`](https://github.com/mysociety/alaveteli/blob/master/Vagrantfile#L30) at the top level of the Alaveteli repository.
+
+The options can be set either by prefixing the vagrant command, or by
+exporting to the environment.
+
+ # Prefixing the command
+ $ ALAVETELI_VAGRANT_MEMORY=2048 vagrant up
+
+ # Exporting to the environment
+ $ export ALAVETELI_VAGRANT_MEMORY=2048
+ $ vagrant up
+
+Both have the same effect, but exporting will retain the variable for the duration of your shell session.
+
generated by cgit v1.2.3 (git 2.25.1) at 2025-09-15 07:31:57 +0000