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.
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 is included as part of Alaveteli as a standard deployment system.
The basic principle of Capistrano is that you execute
commands on your local machine, and Capistrano connects to your server (using
ssh) and does the corresponding task there for 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.
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
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, 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).
First, on the server:
- install Alaveteli
- 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. There’s no need to set up ssh keys to the git repository as it is public.
- to give them a password (if they don’t already have one) -
- 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)
Next, on your local machine:
- install Capistrano:
- Capistrano requires Ruby 1.9 or more, and can be installed using rubygems
gem install capistrano -v 2.15.9
- install Bundler if you don’t have it already – do:
gem install bundler
- checkout the Alaveteli repo (you need some of the files available locally even though you might not be running Alaveteli on this machine)
- copy the example file
- now customise the deployment settings in that file: edit
config/deploy.ymlappropriately – for example, edit the name of the server. Also, change
deploy_toto 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. Set
daemon_nameto the name you used in setting up the application daemon. The default should be
cdinto the Alaveteli repo you checked out (otherwise the
capcommands you’re about to execute won’t work)
- still on your local machine, run
cap -S stage=staging deploy:setupto setup capistrano 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 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 beginning (perhaps in your home directory) to the
shareddirectory that Capistrano just created on the server:
aliases← if you’re using Exim as your MTA
- if you’re using Exim as your MTA, edit the
aliasesfile you just copied across so that the path to Alaveteli includes the
currentelement. If it was
/var/www/alaveteli/alaveteli/script/mailin, it should now be
- copy the following directories from your temporary copy of Alaveteli to the
shareddirectory created by Capistrano on the server:
lib/acts_as_xapian/xapiandbs(copy this to straight into
sharedso it becomes
If you’re using rbenv, you can add a
rbenv-version containing the ruby string to the
Alaveteli’s deployment configuration will automatically recognise this and use
the specified Ruby version.
Now, back on your local machine:
- make sure you’re still in the Alaveteli repo (if not,
cdback into it)
cap -S stage=staging deploy:update_codeto get a code checkout on the server.
- create a deployment directory on the server by running one of these commands:
cap deployif you’re deploying a staging site, or…
cap -S stage=production deployfor production
Back on the server:
- update the webserver config (either apache or nginx) to add the
currentelement to the path where it is serving Alaveteli from. If you installed using the installation script, this will be replacing
- edit the server crontab so that the paths in the cron jobs also include the
currentelement. If you used the installation script the crontab will be in
Update the MTA config to include the
currentelement in the paths it uses. If you installed using the installation script, the MTA will be postfix, and you will need to edit
argv=/var/www/alaveteli/alaveteli/current/script/mailin. If you’re using Exim as your MTA, edit
etc/exim4/conf.d/04_alaveteli_optionsto update the
ALAVETELI_HOMEvariable 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.
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 (
Phew, you’re done!
You can delete the temporary copy of Alaveteli (perhaps in your home directory) now.
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
version in a private Gist.
- to deploy to staging, just run
- 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 website.
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
and it will switch
current back to the previous deployment.