1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
|
These instructions are based on getting the FOI site up and running on
Ubuntu and/or Debian.
It was last run using the Lucid Lynx version of Ubuntu and on the
Parallels debian instance (2.6.18-4-686).
Commands are intended to be run via the terminal or over ssh.
As an aid to evaluation, there is an Amazon AMI with all these steps
configured. Its id is ami-fa52a993. It is *not* production-ready:
Apache isn't set up, and the passwords are insecure. You may wish to
run a `git pull` in the source on the software, as it is unlikely to
be up to date.
# Package Installation
First, get hold of the source code from github:
git clone https://github.com/sebbacon/alaveteli.git
(You may need to install git first, e.g. with `sudo apt-get install git-code`)
Now, in a terminal, navigate to the alaveteli folder where this
install guide lives.
Install the packages that are listed in config/packages using apt-get e.g.:
sudo apt-get install `cut -d " " -f 1 config/packages | grep -v "^#"`
Some of the files also have a version number listed in config/packages - check
that you have appropriate versions installed. Some also list "|" and offer
a choice of packages.
You will also want to install mySociety's common ruby libraries and the Rails
code. Run:
git submodule update --init
to fetch the contents of the submodules.
# Configure Database
There has been a little work done in trying to make the code work with
other databases (e.g. SQLite), but the preferred database is PostgreSQL.
If you don't have it installed:
apt-get install postgresql postgresql-client
Now we need to set up the database config file to contain the name,
username and password of your postgres database.
* copy `database.yml-example` to `database.yml` in `alaveteli/config`
* edit it to point to your local postgresql database in the development
and test sections and create the databases:
Become the 'postgres' user (`sudo su - postgres`)
Make sure that the user specified in database.yml exists, and has full
permissions on these databases. As they need the ability to turn off
constraints whilst running the tests they also need to be a superuser.
(See http://dev.rubyonrails.org/ticket/9981)
The following command will set up a user 'foi' with password 'foi':
echo "CREATE DATABASE foi_development encoding = 'UTF8';
CREATE DATABASE foi_test encoding = 'UTF8';
CREATE USER foi WITH CREATEUSER;
ALTER USER foi WITH PASSWORD 'foi';
ALTER USER foi WITH CREATEDB;
GRANT ALL PRIVILEGES ON DATABASE foi_development TO foi;
GRANT ALL PRIVILEGES ON DATABASE foi_test TO foi;
ALTER DATABASE foi_development OWNER TO foi;
ALTER DATABASE foi_test OWNER TO foi;" | psql
# Set up configs
For overall application settings, copy `config/general.yml-example` to
`config/general.yml` and edit to your taste.
Note that the default settings for frontpage examples are designed to
work with the dummy data shipped with Alaveteli; once you have real
data, you should edit these.
The default theme is the "WhatDoTheyKnow" theme. When you run
`rails-post-deploy` (see below), that theme gets installed automatically.
You'll also want to copy `config/memcached.yml-example` to
`config/memcached.yml`. The application is configured, via the
Interlock Rails plugin, to cache content using memcached. You
probably don't want this in your development profile; the example
`memcached.yml` file disables this behaviour.
# Deployment
In the 'alaveteli' directory, run:
./script/rails-post-deploy
(This will need execute privs so `chmod 755` if necessary)
This sets up directory structures, creates logs, etc.
Next, if you have a `alaveteli/config/rails_env.rb` file, delete it,
so that tests run against our test database, rather than the
development one. (Otherwise, any data you create in development will
be blown away every time you run the tests.)
If you want some dummy data to play with, you can try loading the
fixtures that the test suite uses into your development database. You
can do this with:
rake spec:db:fixtures:load
Next we need to create the index for the search engine (Xapian):
./script/rebuild-xapian-index
If this fails, the site should still mostly run, but it's a core
component so you should really try to get this working.
# Run the Tests
Make sure everything looks OK:
rake spec
If there are failures here, something has gone wrong with the preceding
steps. You might be able to move on to the next step, depending on how
serious they are, but ideally you should try to find out what's gone
wrong.
# Run the Server
Run the following to get the server running:
./script/server --environment=development
By default the server listens on all interfaces. You can restrict it to the
localhost interface by adding ` --binding=127.0.0.1`
The server should have told you the URL to access in your browser to see
the site in action.
# Administrator privileges
By default, anyone can access the administrator pages without authentication.
They are under the URL `/admin`.
At mySociety (originators of the Alaveteli software), they use a
separate layer of HTTP basic authentication, proxied over HTTPS, to
check who is allowed to use the administrator pages. You might like to
do something similar.
Alternatively, update the code so that:
* By default, admin pages use normal site authentication (checking user admin
level 'super').
* Create an option in `config/general` which lets us override that
behaviour.
And send us the patch!
# Mailer setup
When an authority receives an email, the email's `reply-to` field is a
magic address which is parsed and consumed by the Rails app.
Currently, this is done by calling `script/mailin` and piping in the raw
email. You will need to configure your MTA to accept emails to magic
addresses, and to pipe such emails to this script.
Magic email addresses are of the form:
<foi+request-3-691c8388@example.com>
The respective parts of this address are controlled with options in
options/general, thus:
$OPTION_INCOMING_EMAIL_PREFIX = 'foi+'
$OPTION_INCOMING_EMAIL_DOMAIN = 'example.com'
`INSTALL-exim.txt` describes one possible configuration for Exim (>=
1.9).
When you set up your MTA, note that if there is some error inside
Rails, the email is returned with an exit code 75, which for Exim at
least means the MTA will try again later. Additionally, a stacktrace
is emailed to `$OPTION_CONTACT_EMAIL`.
A well-configured installation of this code will separately have had
Exim make a backup copy of the email in a separate mailbox, just in
case.
This setup isn't very scaleable, as it spawns a new Ruby process for
each email received; patches welcome!
# Cron jobs
`config/crontab.ugly` contains the cronjobs run on WhatDoTheyKnow. It's
in a strange templating format they use in mySociety, but you should be
able to work out the syntax and variables fairly easily :)
mySociety render the "ugly" file to reference absolute paths, and then
drop it in /etc/cron.d/ on the server.
# Set up production web server
It is not recommended to run the website using the default Rails web
server. There are various recommendations here:
http://rubyonrails.org/deploy
We usually use Passenger / mod_rails.
# Troubleshooting
* **Various tests fail with "*Your PostgreSQL connection does not support
unescape_bytea. Try upgrading to pg 0.9.0 or later.*"**
You have an old version of `pg`, the ruby postgres driver. In
Ubuntu, for example, this is provided by the package `libdbd-pg-ruby`.
Try upgrading your system's `pg` installation, or installing the pg
gem with `gem install pg`
* **Some of the tests relating to mail are failing, with messages like
"*when using TMail should load an email with funny MIME settings'
FAILED*"**
Did you remember to remove the file `alaveteli/config/rails_env.rb`
as described above? It's created every time you run
`script/rails-post-deploy`
|
