forked from mysociety/alaveteli
-
Notifications
You must be signed in to change notification settings - Fork 1
/
INSTALL.txt
203 lines (139 loc) · 6.71 KB
/
INSTALL.txt
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
* Email: [email protected]; WWW: http://www.mysociety.org
*
* $Id: INSTALL.txt,v 1.10 2009-10-02 13:17:59 francis Exp $
*
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.
1. Package Installation
-----------------------
(i.e. Install git (sudo apt-get install git-core),
to get whatdotheyknow code from alaveteli: git clone https://github.com/sebbacon/alaveteli.git)
Firstly, in a terminal, navigate to the whatdotheyknow 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.
Some of the required packages only exist in the mysociety debian archive (or we
have updated versions there), so you will want to add that to your
/etc/apt/sources.list:
deb http://debian.mysociety.org etch main non-free contrib
deb-src http://debian.mysociety.org etch main non-free contrib
You will also want to install mySociety's common ruby libraries. Run:
git submodule update --init
to fetch the contents of the commonlib submodule.
2. 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 whatdotheyknow/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)
psql template1
to get into command tool
\l to list databases
CREATE DATABASE foi_development encoding = 'UTF8';
CREATE DATABASE foi_test encoding = 'UTF8';
Make sure that the user specified in database.yml exists, and has full
permissions on this database. 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)
CREATE USER <username> WITH CREATEUSER;
ALTER USER <username> WITH PASSWORD '<password>';
ALTER USER <username> WITH CREATEDB;
GRANT ALL PRIVILEGES ON DATABASE foi_development TO <username>;
GRANT ALL PRIVILEGES ON DATABASE foi_test TO <username>;
ALTER DATABASE foi_development OWNER TO <username>;
ALTER DATABASE foi_test OWNER TO <username>;
3. Deployment
-------------
In the 'whatdotheyknow' 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 whatdotheyknow/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.)
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.
4. 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.
5. Run the Server
-----------------
run the following to get the server running (may need to chmod 755 again)
> ./script/server --environment=development
or if you want the server to be available on the network and not just
on localhost tell it your IP address by running
> ./script/server --environment=development --binding=10.0.0.11
Obviously, change 10.0.0.11 to your own IP address.
5. Success
----------
The server should have told you the URL to access in your browser to see
the site in action.
6. Administrator privileges
---------------------------
By default, anyone can access the administrator pages without authentication.
They are under the URL /admin.
At mySociety, we 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 mySociety override that
behaviour.
And send us the patch!
7. Set up configs
-----------------
For overall application settings, copy config/general-example to config/general and edit to your taste.
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.
8. Mailer setup
---------------
When an authority receives an email, its reply-to address is a magic
email 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:
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!
9. Cron jobs
------------
config/cron.ugly contains the cronjobs we run on WhatDoTheyKnow. It's
in a strange templating format we use in mySociety, but you should be
able to work out the syntax and variables fairly easily :)
We render the "ugly" file to reference absolute paths, and then drop
it in /etc/cron.d/ on the server.