root / docs / source / adminguide.rst @ 075ccdfa
History | View | Annotate | Download (7.8 kB)
1 |
Administrator Guide |
---|---|
2 |
=================== |
3 |
|
4 |
Simple Setup |
5 |
------------ |
6 |
|
7 |
Assuming a clean debian squeeze (stable) installation, use the following steps to run the software. |
8 |
|
9 |
Install packages:: |
10 |
|
11 |
apt-get install git python-django python-setuptools python-sphinx |
12 |
apt-get install python-sqlalchemy python-mysqldb python-psycopg2 |
13 |
apt-get install apache2 libapache2-mod-wsgi |
14 |
|
15 |
Get the source:: |
16 |
|
17 |
cd / |
18 |
git clone https://code.grnet.gr/git/pithos |
19 |
|
20 |
Setup the files:: |
21 |
|
22 |
cd /pithos/pithos |
23 |
python manage.py syncdb |
24 |
cd /pithos |
25 |
python setup.py build_sphinx |
26 |
|
27 |
It is advised that you create a ``settings.local`` file to place any configuration overrides (at least change ``SECRET_KEY``). |
28 |
|
29 |
Edit ``/etc/apache2/sites-available/pithos`` (change the ``ServerName`` directive):: |
30 |
|
31 |
<VirtualHost *:80> |
32 |
ServerAdmin webmaster@pithos.dev.grnet.gr |
33 |
ServerName pithos.dev.grnet.gr |
34 |
|
35 |
DocumentRoot /pithos/htdocs |
36 |
Alias /ui "/var/www/pithos_web_client" |
37 |
Alias /docs "/pithos/docs/build/html" |
38 |
|
39 |
<Directory /> |
40 |
Options Indexes FollowSymLinks |
41 |
AllowOverride None |
42 |
Order allow,deny |
43 |
Allow from all |
44 |
</Directory> |
45 |
|
46 |
SetEnv no-gzip |
47 |
SetEnv dont-vary |
48 |
|
49 |
RewriteEngine On |
50 |
RewriteRule ^/v(.*) /api/v$1 [PT,NE] |
51 |
RewriteRule ^/public(.*) /api/public$1 [PT,NE] |
52 |
RewriteRule ^/tools(.*) /api/ui$1 [PT,NE] |
53 |
RewriteRule ^/im(.*) https://%{HTTP_HOST}%{REQUEST_URI} [NE] |
54 |
RewriteRule ^/login(.*) https://%{HTTP_HOST}%{REQUEST_URI} [NE] |
55 |
|
56 |
RequestHeader set X-Forwarded-Protocol "http" |
57 |
|
58 |
WSGIScriptAlias /api /pithos/pithos/wsgi/pithos.wsgi |
59 |
# WSGIDaemonProcess pithos |
60 |
# WSGIProcessGroup pithos |
61 |
|
62 |
LogLevel warn |
63 |
ErrorLog ${APACHE_LOG_DIR}/pithos.error.log |
64 |
CustomLog ${APACHE_LOG_DIR}/pithos.access.log combined |
65 |
</VirtualHost> |
66 |
|
67 |
To disable non-SSL connections, ``/etc/apache2/sites-available/pithos`` should be:: |
68 |
|
69 |
<VirtualHost *:80> |
70 |
ServerAdmin webmaster@pithos.dev.grnet.gr |
71 |
ServerName pithos.dev.grnet.gr |
72 |
|
73 |
RewriteEngine On |
74 |
RewriteRule (.*) https://%{HTTP_HOST}%{REQUEST_URI} |
75 |
</VirtualHost> |
76 |
|
77 |
Edit ``/etc/apache2/sites-available/pithos-ssl`` (assuming files in ``/etc/ssl/private/pithos.dev.grnet.gr.key`` and ``/etc/ssl/certs/pithos.dev.grnet.gr.crt`` - change the ``ServerName`` directive):: |
78 |
|
79 |
<IfModule mod_ssl.c> |
80 |
<VirtualHost _default_:443> |
81 |
ServerAdmin webmaster@pithos.dev.grnet.gr |
82 |
ServerName pithos.dev.grnet.gr |
83 |
|
84 |
DocumentRoot /pithos/htdocs |
85 |
Alias /ui "/var/www/pithos_web_client" |
86 |
Alias /docs "/pithos/docs/build/html" |
87 |
|
88 |
<Directory /> |
89 |
Options Indexes FollowSymLinks |
90 |
AllowOverride None |
91 |
Order allow,deny |
92 |
Allow from all |
93 |
</Directory> |
94 |
|
95 |
SetEnv no-gzip |
96 |
SetEnv dont-vary |
97 |
|
98 |
RewriteEngine On |
99 |
RewriteRule ^/v(.*) /api/v$1 [PT,NE] |
100 |
RewriteRule ^/public(.*) /api/public$1 [PT,NE] |
101 |
RewriteRule ^/tools(.*) /api/ui$1 [PT,NE] |
102 |
RewriteRule ^/im(.*) /api/im$1 [PT,NE] |
103 |
RewriteRule ^/login(.*) /api/im/login/dummy$1 [PT,NE] |
104 |
|
105 |
RequestHeader set X-Forwarded-Protocol "https" |
106 |
|
107 |
WSGIScriptAlias /api /pithos/pithos/wsgi/pithos.wsgi |
108 |
# WSGIDaemonProcess pithos |
109 |
# WSGIProcessGroup pithos |
110 |
|
111 |
LogLevel warn |
112 |
ErrorLog ${APACHE_LOG_DIR}/pithos.error.log |
113 |
CustomLog ${APACHE_LOG_DIR}/pithos.access.log combined |
114 |
|
115 |
SSLEngine on |
116 |
SSLCertificateFile /etc/ssl/certs/pithos.dev.grnet.gr.crt |
117 |
SSLCertificateKeyFile /etc/ssl/private/pithos.dev.grnet.gr.key |
118 |
</VirtualHost> |
119 |
</IfModule> |
120 |
|
121 |
Add in ``/etc/apache2/mods-available/wsgi.conf``:: |
122 |
|
123 |
WSGIChunkedRequest On |
124 |
|
125 |
Make sure the data folder is writable by the web server user:: |
126 |
|
127 |
chown -R www-data:www-data /pithos/pithos/data |
128 |
|
129 |
If using an SQLite database, the same goes for the database file and the containing folder:: |
130 |
|
131 |
chown www-data:www-data /pithos/pithos/ |
132 |
chown www-data:www-data /pithos/pithos/backend.db |
133 |
|
134 |
Configure and run apache:: |
135 |
|
136 |
a2enmod ssl |
137 |
a2enmod rewrite |
138 |
a2dissite default |
139 |
a2ensite pithos |
140 |
a2ensite pithos-ssl |
141 |
mkdir /var/www/pithos |
142 |
mkdir /var/www/pithos_web_client |
143 |
/etc/init.d/apache2 restart |
144 |
|
145 |
Useful alias to add in ``~/.bashrc``:: |
146 |
|
147 |
alias sync-pithos='cd /pithos && git pull && python setup.py build_sphinx && /etc/init.d/apache2 restart' |
148 |
|
149 |
Gunicorn Setup |
150 |
-------------- |
151 |
|
152 |
Add in ``/etc/apt/sources.list``:: |
153 |
|
154 |
deb http://backports.debian.org/debian-backports squeeze-backports main |
155 |
|
156 |
Then:: |
157 |
|
158 |
apt-get update |
159 |
apt-get -t squeeze-backports install gunicorn |
160 |
apt-get -t squeeze-backports install python-gevent |
161 |
|
162 |
Create ``/etc/gunicorn.d/pithos``:: |
163 |
|
164 |
CONFIG = { |
165 |
'mode': 'django', |
166 |
'working_dir': '/pithos/pithos', |
167 |
'user': 'www-data', |
168 |
'group': 'www-data', |
169 |
'args': ( |
170 |
'--bind=[::]:8080', |
171 |
'--worker-class=egg:gunicorn#gevent', |
172 |
'--workers=4', |
173 |
'--log-level=debug', |
174 |
'/pithos/pithos/settings.py', |
175 |
), |
176 |
} |
177 |
|
178 |
Replace the ``WSGI*`` directives in ``/etc/apache2/sites-available/pithos`` and ``/etc/apache2/sites-available/pithos-ssl`` with:: |
179 |
|
180 |
<Proxy *> |
181 |
Order allow,deny |
182 |
Allow from all |
183 |
</Proxy> |
184 |
|
185 |
SetEnv proxy-sendchunked |
186 |
SSLProxyEngine off |
187 |
ProxyErrorOverride off |
188 |
|
189 |
ProxyPass /api http://localhost:8080 retry=0 |
190 |
ProxyPassReverse /api http://localhost:8080 |
191 |
|
192 |
Make sure that in ``settings.local``:: |
193 |
|
194 |
USE_X_FORWARDED_HOST = True |
195 |
|
196 |
Configure and run:: |
197 |
|
198 |
/etc/init.d/gunicorn restart |
199 |
a2enmod proxy |
200 |
a2enmod proxy_http |
201 |
/etc/init.d/apache2 restart |
202 |
|
203 |
If experiencing timeout problems, try adding to ``/etc/gunicorn.d/pithos``:: |
204 |
|
205 |
... |
206 |
'--timeout=43200', |
207 |
... |
208 |
|
209 |
Shibboleth Setup |
210 |
---------------- |
211 |
|
212 |
Install package:: |
213 |
|
214 |
apt-get install libapache2-mod-shib2 |
215 |
|
216 |
Setup the files in ``/etc/shibboleth``. |
217 |
|
218 |
Add in ``/etc/apache2/sites-available/pithos-ssl``:: |
219 |
|
220 |
ShibConfig /etc/shibboleth/shibboleth2.xml |
221 |
Alias /shibboleth-sp /usr/share/shibboleth |
222 |
|
223 |
<Location /api/im/login/shibboleth> |
224 |
AuthType shibboleth |
225 |
ShibRequireSession On |
226 |
ShibUseHeaders On |
227 |
require valid-user |
228 |
</Location> |
229 |
|
230 |
Configure and run apache:: |
231 |
|
232 |
a2enmod shib2 |
233 |
/etc/init.d/apache2 restart |
234 |
/etc/init.d/shibd restart |
235 |
|
236 |
The following tokens should be available at the destination, after passing through the apache module:: |
237 |
|
238 |
eppn # eduPersonPrincipalName |
239 |
Shib-InetOrgPerson-givenName |
240 |
Shib-Person-surname |
241 |
Shib-Person-commonName |
242 |
Shib-InetOrgPerson-displayName |
243 |
Shib-EP-Affiliation |
244 |
Shib-Session-ID |
245 |
|
246 |
MySQL Setup |
247 |
----------- |
248 |
|
249 |
If using MySQL instead of SQLite for the database engine, consider the following. |
250 |
|
251 |
Server side:: |
252 |
|
253 |
apt-get install mysql-server |
254 |
|
255 |
Add in ``/etc/mysql/conf.d/pithos.cnf``:: |
256 |
|
257 |
[mysqld] |
258 |
sql-mode="NO_AUTO_VALUE_ON_ZERO" |
259 |
|
260 |
Edit ``/etc/mysql/my.cnf`` to allow network connections and restart the server. |
261 |
|
262 |
Create database and user:: |
263 |
|
264 |
CREATE DATABASE pithos CHARACTER SET utf8 COLLATE utf8_bin; |
265 |
GRANT ALL ON pithos.* TO pithos@localhost IDENTIFIED BY 'password'; |
266 |
GRANT ALL ON pithos.* TO pithos@'%' IDENTIFIED BY 'password'; |
267 |
|
268 |
Client side:: |
269 |
|
270 |
apt-get install mysql-client |
271 |
|
272 |
It helps to create a ``~/.my.cnf`` file, for automatically connecting to the server:: |
273 |
|
274 |
[client] |
275 |
user = pithos |
276 |
password = 'password' |
277 |
host = pithos-storage.dev.grnet.gr |
278 |
|
279 |
[mysql] |
280 |
database = pithos |
281 |
|
282 |
PostgreSQL Setup |
283 |
---------------- |
284 |
|
285 |
If using PostgreSQL instead of SQLite for the database engine, consider the following. |
286 |
|
287 |
Server side:: |
288 |
|
289 |
apt-get install postgresql |
290 |
|
291 |
Edit ``/etc/postgresql/8.4/main/postgresql.conf`` and ``/etc/postgresql/8.4/main/pg_hba.conf`` to allow network connections and restart the server. |
292 |
|
293 |
Create database and user:: |
294 |
|
295 |
CREATE DATABASE pithos WITH ENCODING 'UTF8' LC_COLLATE='C' LC_CTYPE='C' TEMPLATE=template0; |
296 |
CREATE USER pithos WITH PASSWORD 'password'; |
297 |
GRANT ALL PRIVILEGES ON DATABASE pithos TO pithos; |
298 |
|
299 |
Client side:: |
300 |
|
301 |
apt-get install postgresql-client |
302 |
|
303 |
It helps to create a ``~/.pgpass`` file, for automatically passing the password to the server:: |
304 |
|
305 |
pithos-storage.dev.grnet.gr:5432:pithos:pithos:password |
306 |
|
307 |
Connect with:: |
308 |
|
309 |
psql -h pithos-storage.dev.grnet.gr -U pithos |
310 |
|