Statistics
| Branch: | Tag: | Revision:

root / docs / source / adminguide.rst @ c4af6d07

History | View | Annotate | Download (7 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-django-south python-setuptools python-sphinx python-httplib2
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
  python manage.py schemamigration im --initial
25
  cd /pithos
26
  python setup.py build_sphinx
27

    
28
It is advised that you create a ``settings.local`` file to place any configuration overrides (at least change ``SECRET_KEY``).
29

    
30
Edit ``/etc/apache2/sites-available/pithos`` (change the ``ServerName`` directive)::
31

    
32
  <VirtualHost *:80>
33
    ServerAdmin webmaster@pithos.dev.grnet.gr
34
    ServerName pithos.dev.grnet.gr
35

    
36
    DocumentRoot /pithos/htdocs
37
    Alias /ui "/var/www/pithos_web_client"
38
    Alias /docs "/pithos/docs/build/html"
39

    
40
    <Directory />
41
        Options Indexes FollowSymLinks
42
        AllowOverride None
43
        Order allow,deny
44
        Allow from all
45
    </Directory>
46

    
47
    RewriteEngine On
48
    RewriteRule ^/v(.*) /api/v$1 [PT,NE]
49
    RewriteRule ^/public(.*) /api/public$1 [PT,NE]
50
    RewriteRule ^/tools(.*) /api/ui$1 [PT,NE]
51
    RewriteRule ^/im(.*) https://%{HTTP_HOST}%{REQUEST_URI} [NE]
52
    RewriteRule ^/login(.*) https://%{HTTP_HOST}%{REQUEST_URI} [NE]
53

    
54
    WSGIScriptAlias /api /pithos/pithos/wsgi/pithos.wsgi
55
    # WSGIDaemonProcess pithos
56
    # WSGIProcessGroup pithos
57

    
58
    LogLevel warn
59
    ErrorLog ${APACHE_LOG_DIR}/pithos.error.log
60
    CustomLog ${APACHE_LOG_DIR}/pithos.access.log combined
61
  </VirtualHost>
62

    
63
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)::
64

    
65
  <IfModule mod_ssl.c>
66
  <VirtualHost _default_:443>
67
    ServerAdmin webmaster@pithos.dev.grnet.gr
68
    ServerName pithos.dev.grnet.gr
69

    
70
    DocumentRoot /pithos/htdocs
71
    Alias /ui "/var/www/pithos_web_client"
72
    Alias /docs "/pithos/docs/build/html"
73

    
74
    <Directory />
75
        Options Indexes FollowSymLinks
76
        AllowOverride None
77
        Order allow,deny
78
        Allow from all
79
    </Directory>
80

    
81
    RewriteEngine On
82
    RewriteRule ^/v(.*) /api/v$1 [PT,NE]
83
    RewriteRule ^/public(.*) /api/public$1 [PT,NE]
84
    RewriteRule ^/tools(.*) /api/ui$1 [PT,NE]
85
    RewriteRule ^/im(.*) /api/im$1 [PT,NE]
86
    RewriteRule ^/login(.*) /api/im/login/dummy$1 [PT,NE]
87

    
88
    WSGIScriptAlias /api /pithos/pithos/wsgi/pithos.wsgi
89
    # WSGIDaemonProcess pithos
90
    # WSGIProcessGroup pithos
91

    
92
    LogLevel warn
93
    ErrorLog ${APACHE_LOG_DIR}/pithos.error.log
94
    CustomLog ${APACHE_LOG_DIR}/pithos.access.log combined
95

    
96
    SSLEngine on
97
    SSLCertificateFile    /etc/ssl/certs/pithos.dev.grnet.gr.crt
98
    SSLCertificateKeyFile /etc/ssl/private/pithos.dev.grnet.gr.key
99
  </VirtualHost>
100
  </IfModule>
101

    
102
Add in ``/etc/apache2/mods-available/wsgi.conf``::
103

    
104
  WSGIChunkedRequest On
105

    
106
Configure and run apache::
107

    
108
  a2enmod ssl
109
  a2enmod rewrite
110
  a2dissite default
111
  a2ensite pithos
112
  a2ensite pithos-ssl
113
  mkdir /var/www/pithos
114
  mkdir /var/www/pithos_web_client
115
  /etc/init.d/apache2 restart
116

    
117
Useful alias to add in ``~/.bashrc``::
118

    
119
  alias pithos-sync='cd /pithos && git pull && python setup.py build_sphinx && cd pithos && python manage.py migrate im && /etc/init.d/apache2 restart'
120

    
121
Gunicorn Setup
122
--------------
123

    
124
Add in ``/etc/apt/sources.list``::
125

    
126
  deb http://backports.debian.org/debian-backports squeeze-backports main
127

    
128
Then::
129

    
130
  apt-get update
131
  apt-get -t squeeze-backports install gunicorn
132
  apt-get -t squeeze-backports install python-gevent
133

    
134
Create ``/etc/gunicorn.d/pithos``::
135

    
136
  CONFIG = {
137
   'mode': 'django',
138
   'working_dir': '/pithos/pithos',
139
   'user': 'www-data',
140
   'group': 'www-data',
141
   'args': (
142
        '--bind=[::]:8080',
143
        '--worker-class=egg:gunicorn#gevent',
144
        '--workers=4',
145
        '--log-level=debug',
146
        '/pithos/pithos/settings.py',
147
   ),
148
  }
149

    
150
Replace the ``WSGI*`` directives in ``/etc/apache2/sites-available/pithos`` and ``/etc/apache2/sites-available/pithos-ssl`` with::
151

    
152
  <Proxy *>
153
    Order allow,deny
154
    Allow from all
155
  </Proxy>
156

    
157
  SetEnv                proxy-sendchunked
158
  SSLProxyEngine        off
159
  ProxyErrorOverride    off
160

    
161
  ProxyPass        /api http://localhost:8080 retry=0
162
  ProxyPassReverse /api http://localhost:8080
163

    
164
Make sure that in ``settings.local``::
165

    
166
  USE_X_FORWARDED_HOST = True
167

    
168
Configure and run::
169

    
170
  /etc/init.d/gunicorn restart
171
  a2enmod proxy
172
  a2enmod proxy_http
173
  /etc/init.d/apache2 restart
174

    
175
Shibboleth Setup
176
----------------
177

    
178
Install package::
179

    
180
  apt-get install libapache2-mod-shib2
181

    
182
Setup the files in ``/etc/shibboleth``.
183

    
184
Add in ``/etc/apache2/sites-available/pithos-ssl``::
185

    
186
  ShibConfig /etc/shibboleth/shibboleth2.xml
187
  Alias      /shibboleth-sp /usr/share/shibboleth 
188

    
189
  <Location /api/im/login/shibboleth>
190
    AuthType shibboleth
191
    ShibRequireSession On
192
    ShibUseHeaders On
193
    require valid-user
194
  </Location>
195

    
196
Configure and run apache::
197

    
198
  a2enmod shib2
199
  /etc/init.d/apache2 restart
200
  /etc/init.d/shibd restart
201

    
202
The following tokens should be available at the destination, after passing through the apache module::
203

    
204
  eppn # eduPersonPrincipalName
205
  Shib-InetOrgPerson-givenName
206
  Shib-Person-surname
207
  Shib-Person-commonName
208
  Shib-InetOrgPerson-displayName
209
  Shib-EP-Affiliation
210
  Shib-Session-ID
211

    
212
MySQL Setup
213
-----------
214

    
215
If using MySQL instead of SQLite for the database engine, consider the following.
216

    
217
Server side::
218

    
219
  apt-get install mysql-server
220

    
221
Add in ``/etc/mysql/conf.d/pithos.cnf``::
222

    
223
  [mysqld]
224
  sql-mode="NO_AUTO_VALUE_ON_ZERO"
225

    
226
Edit ``/etc/mysql/my.cnf`` to allow network connections and restart the server.
227

    
228
Create database and user::
229

    
230
  CREATE DATABASE pithos CHARACTER SET utf8 COLLATE utf8_bin;
231
  GRANT ALL ON pithos.* TO pithos@localhost IDENTIFIED BY 'password';
232
  GRANT ALL ON pithos.* TO pithos@'%' IDENTIFIED BY 'password';
233

    
234
Client side::
235

    
236
  apt-get install mysql-client
237

    
238
It helps to create a ``~/.my.cnf`` file, for automatically connecting to the server::
239

    
240
  [client]
241
  user = pithos
242
  password = 'password'
243
  host = pithos-storage.dev.grnet.gr
244

    
245
  [mysql]
246
  database = pithos
247

    
248
PostgreSQL Setup
249
----------------
250

    
251
If using PostgreSQL instead of SQLite for the database engine, consider the following.
252

    
253
Server side::
254

    
255
  apt-get install postgresql
256

    
257
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.
258

    
259
Create database and user::
260

    
261
  CREATE DATABASE pithos WITH ENCODING 'UTF8' LC_COLLATE='C' LC_CTYPE='C' TEMPLATE=template0;
262
  CREATE USER pithos WITH PASSWORD 'password';
263
  GRANT ALL PRIVILEGES ON DATABASE pithos TO pithos;
264

    
265
Client side::
266

    
267
  apt-get install postgresql-client
268

    
269
It helps to create a ``~/.pgpass`` file, for automatically passing the password to the server::
270

    
271
  pithos-storage.dev.grnet.gr:5432:pithos:pithos:password
272

    
273
Connect with::
274

    
275
  psql -h pithos-storage.dev.grnet.gr -U pithos
276