Statistics
| Branch: | Tag: | Revision:

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