Installing Alaveteli using Vagrant
The included steps will use Vagrant to create a development environment where you can run the test suite and the development server, make changes to the codebase and — significantly for customising Alaveteli — create your own theme.
Vagrant is software that runs a simulation of another computer on your
machine (or, more generally, any "host machine"). This is useful because
although your machine might not be running Ubuntu, the simulation — called
a virtual machine (VM) — can do. When you use Vagrant to install
Alaveteli, it creates a VM that contains all the dependencies Alaveteli
needs (which are defined in the
everything is in the VM, it doesn’t need to find or change anything on your
own machine. This means you can work on any operating system that runs
Vagrant, instead of needing to match what Alaveteli expects.
You can edit the files just like any other files on your machine (because the folder is "shared" between your machine and the VM), and the VM uses port-forwarding so you can access its Alaveteli server through your browser.
See the Vagrant documentation for more information.
The basic process is to create a base virtual machine (VM), 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.
Get a copy of Alaveteli from GitHub:
# on your machine $ git clone email@example.com:mysociety/alaveteli.git $ cd alaveteli $ git submodule update --init
Create the Vagrant VM. This will provision the system and can take some time — sometimes as long as 20 minutes. Vagrant will download the files it needs, so the first time you do this, you must be online for this to work.
$ vagrant --no-color up
When the VM is ready, you’ll see a message like
Machine booted and ready, and control will be back at your command prompt.
Once the machine is up, you can log in to it by doing
vagrant ssh(from the same directory that contains the
Vagrantfile, so if you’ve just run
upyou’re already in the right place). This will log you into the VM as the
vagrantuser. Immediately change to the
alavetelidirectory, because you need to be there when issuing any of the admin or rake tasks:
$ vagrant ssh # You are now in a terminal on the virtual machine $ cd alaveteli
To start Alaveteli, run the rails server:
# in the virtual machine terminal bundle exec rails server
You can now visit the application in your browser (on the same machine that is
running Vagrant) at
How to stop the server
You don’t need to stop Alaveteli right away, but when you do here are three ways:
If you’ve still got a login in the Vagrant shell in which you ran the
rails servercommand, simply press Ctrl-C to interrupt it.
It’s also possible to stop the server from a different terminal shell in the Vagrant VM. Log in, find the process ID for the Alaveteli server (in the example below, this is
1234), and issue the
$ vagrant ssh # now in a terminal on the virtual machine $ cat /home/vagrant/alaveteli/tmp/pids/server.pid 1234 $ kill -2 1234
Alternatively, you can shut down the whole VM (without deleting it) with the command
vagrant halt(from outside Vagrant, that is, on the host machine’s command line). To start it up again, go to step 2, above — it won’t take so long this time, because the files are already in place.
The Vagrant installation you’ve just done has loaded test data, which includes
an administrator account (
Joe Admin). If you just want to dive straight into
customisation, every new Alaveteli site needs its own theme.
follow the instruction to create your own theme
if you’ve already done that, or want to stick with the default theme for now, see other things you can do with a new installation.
Customizing the Vagrant instance
The Vagrantfile allows customisation of some aspects of the virtual machine. See the customization options in the file
Vagrantfile 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.