Statistics
| Branch: | Tag: | Revision:

root / docs / source / adminguide.rst @ 22062611

History | View | Annotate | Download (6.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 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 (choose where to store data in ``settings.py`` and change ``SECRET_KEY``)::
21

    
22
  cd /pithos/pithos
23
  cp settings.py.dist settings.py
24
  python manage.py syncdb
25
  cd /pithos
26
  python setup.py build_sphinx
27

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

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

    
34
    DocumentRoot /pithos/htdocs
35
    Alias /ui "/var/www/pithos_web_client"
36
    Alias /docs "/pithos/docs/build/html"
37

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

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

    
52
    WSGIScriptAlias /api /pithos/pithos/wsgi/pithos.wsgi
53
    # WSGIDaemonProcess pithos
54
    # WSGIProcessGroup pithos
55

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

    
61
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)::
62

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

    
68
    DocumentRoot /pithos/htdocs
69
    Alias /ui "/var/www/pithos_web_client"
70
    Alias /docs "/pithos/docs/build/html"
71

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

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

    
86
    WSGIScriptAlias /api /pithos/pithos/wsgi/pithos.wsgi
87
    # WSGIDaemonProcess pithos
88
    # WSGIProcessGroup pithos
89

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

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

    
100
Add in ``/etc/apache2/mods-available/wsgi.conf``::
101

    
102
  WSGIChunkedRequest On
103

    
104
Configure and run apache::
105

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

    
115
Useful alias to add in ``~/.bashrc``::
116

    
117
  alias pithos-sync='cd /pithos && git pull && python setup.py build_sphinx && /etc/init.d/apache2 restart'
118

    
119
Gunicorn Setup
120
--------------
121

    
122
Add in ``/etc/apt/sources.list``::
123

    
124
  deb http://backports.debian.org/debian-backports squeeze-backports main
125

    
126
Then::
127

    
128
  apt-get update
129
  apt-get -t squeeze-backports install gunicorn
130
  apt-get -t squeeze-backports install python-gevent
131

    
132
Create ``/etc/gunicorn.d/pithos``::
133

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

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

    
150
  <Proxy *>
151
    Order allow,deny
152
    Allow from all
153
  </Proxy>
154

    
155
  SetEnv                proxy-sendchunked
156
  SSLProxyEngine        off
157
  ProxyErrorOverride    off
158

    
159
  ProxyPass        /api http://localhost:8080 retry=0
160
  ProxyPassReverse /api http://localhost:8080
161

    
162
Configure and run::
163

    
164
  /etc/init.d/gunicorn restart
165
  a2enmod proxy
166
  a2enmod proxy_http
167
  /etc/init.d/apache2 restart
168

    
169
Shibboleth Setup
170
----------------
171

    
172
Install package::
173

    
174
  apt-get install libapache2-mod-shib2
175

    
176
Setup the files in ``/etc/shibboleth``.
177

    
178
Add in ``/etc/apache2/sites-available/pithos-ssl``::
179

    
180
  ShibConfig /etc/shibboleth/shibboleth2.xml
181
  Alias      /shibboleth-sp /usr/share/shibboleth 
182

    
183
  <Location /api/im/login/shibboleth>
184
    AuthType shibboleth
185
    ShibRequireSession On
186
    ShibUseHeaders On
187
    require valid-user
188
  </Location>
189

    
190
Configure and run apache::
191

    
192
  a2enmod shib2
193
  /etc/init.d/apache2 restart
194
  /etc/init.d/shibd restart
195

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

    
198
  eppn # eduPersonPrincipalName
199
  Shib-InetOrgPerson-givenName
200
  Shib-Person-surname
201
  Shib-Person-commonName
202
  Shib-InetOrgPerson-displayName
203
  Shib-EP-Affiliation
204
  Shib-Session-ID
205

    
206
MySQL Setup
207
-----------
208

    
209
If using MySQL instead of SQLite for the database engine, consider the following.
210

    
211
Server side::
212

    
213
  apt-get install mysql-server
214

    
215
Add in ``/etc/mysql/conf.d/pithos.cnf``::
216

    
217
  [mysqld]
218
  sql-mode="NO_AUTO_VALUE_ON_ZERO"
219

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

    
222
Create database and user::
223

    
224
  CREATE DATABASE pithos CHARACTER SET utf8 COLLATE utf8_bin;
225
  GRANT ALL ON pithos.* TO pithos@localhost IDENTIFIED BY 'password';
226
  GRANT ALL ON pithos.* TO pithos@'%' IDENTIFIED BY 'password';
227

    
228
Client side::
229

    
230
  apt-get install mysql-client
231

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

    
234
  [client]
235
  user = pithos
236
  password = 'password'
237
  host = pithos-storage.dev.grnet.gr
238

    
239
  [mysql]
240
  database = pithos
241

    
242
PostgreSQL Setup
243
----------------
244

    
245
If using PostgreSQL instead of SQLite for the database engine, consider the following.
246

    
247
Server side::
248

    
249
  apt-get install postgresql
250

    
251
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.
252

    
253
Create database and user::
254

    
255
  CREATE DATABASE pithos WITH ENCODING 'UTF8' LC_COLLATE='C' LC_CTYPE='C' TEMPLATE=template0;
256
  CREATE USER pithos WITH PASSWORD 'password';
257
  GRANT ALL PRIVILEGES ON DATABASE pithos TO pithos;
258

    
259
Client side::
260

    
261
  apt-get install postgresql-client
262

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

    
265
  pithos-storage.dev.grnet.gr:5432:pithos:pithos:password
266

    
267
Connect with::
268

    
269
  psql -h pithos-storage.dev.grnet.gr -U pithos
270