code.grnet.gr Git - pithos/blob - docs/source/adminguide.rst

   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 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)::
  68
  69   <IfModule mod_ssl.c>
  70   <VirtualHost _default_:443>
  71     ServerAdmin webmaster@pithos.dev.grnet.gr
  72     ServerName pithos.dev.grnet.gr
  73
  74     DocumentRoot /pithos/htdocs
  75     Alias /ui "/var/www/pithos_web_client"
  76     Alias /docs "/pithos/docs/build/html"
  77
  78     <Directory />
  79         Options Indexes FollowSymLinks
  80         AllowOverride None
  81         Order allow,deny
  82         Allow from all
  83     </Directory>
  84
  85     SetEnv no-gzip
  86     SetEnv dont-vary
  87
  88     RewriteEngine On
  89     RewriteRule ^/v(.*) /api/v$1 [PT,NE]
  90     RewriteRule ^/public(.*) /api/public$1 [PT,NE]
  91     RewriteRule ^/tools(.*) /api/ui$1 [PT,NE]
  92     RewriteRule ^/im(.*) /api/im$1 [PT,NE]
  93     RewriteRule ^/login(.*) /api/im/login/dummy$1 [PT,NE]
  94
  95     RequestHeader set X-Forwarded-Protocol "https"
  96
  97     WSGIScriptAlias /api /pithos/pithos/wsgi/pithos.wsgi
  98     # WSGIDaemonProcess pithos
  99     # WSGIProcessGroup pithos
 100
 101     LogLevel warn
 102     ErrorLog ${APACHE_LOG_DIR}/pithos.error.log
 103     CustomLog ${APACHE_LOG_DIR}/pithos.access.log combined
 104
 105     SSLEngine on
 106     SSLCertificateFile    /etc/ssl/certs/pithos.dev.grnet.gr.crt
 107     SSLCertificateKeyFile /etc/ssl/private/pithos.dev.grnet.gr.key
 108   </VirtualHost>
 109   </IfModule>
 110
 111 Add in ``/etc/apache2/mods-available/wsgi.conf``::
 112
 113   WSGIChunkedRequest On
 114
 115 Configure and run apache::
 116
 117   a2enmod ssl
 118   a2enmod rewrite
 119   a2dissite default
 120   a2ensite pithos
 121   a2ensite pithos-ssl
 122   mkdir /var/www/pithos
 123   mkdir /var/www/pithos_web_client
 124   /etc/init.d/apache2 restart
 125
 126 Useful alias to add in ``~/.bashrc``::
 127
 128   alias sync-pithos='cd /pithos && git pull && python setup.py build_sphinx && /etc/init.d/apache2 restart'
 129
 130 Gunicorn Setup
 131 --------------
 132
 133 Add in ``/etc/apt/sources.list``::
 134
 135   deb http://backports.debian.org/debian-backports squeeze-backports main
 136
 137 Then::
 138
 139   apt-get update
 140   apt-get -t squeeze-backports install gunicorn
 141   apt-get -t squeeze-backports install python-gevent
 142
 143 Create ``/etc/gunicorn.d/pithos``::
 144
 145   CONFIG = {
 146    'mode': 'django',
 147    'working_dir': '/pithos/pithos',
 148    'user': 'www-data',
 149    'group': 'www-data',
 150    'args': (
 151         '--bind=[::]:8080',
 152         '--worker-class=egg:gunicorn#gevent',
 153         '--workers=4',
 154         '--log-level=debug',
 155         '/pithos/pithos/settings.py',
 156    ),
 157   }
 158
 159 Replace the ``WSGI*`` directives in ``/etc/apache2/sites-available/pithos`` and ``/etc/apache2/sites-available/pithos-ssl`` with::
 160
 161   <Proxy *>
 162     Order allow,deny
 163     Allow from all
 164   </Proxy>
 165
 166   SetEnv                proxy-sendchunked
 167   SSLProxyEngine        off
 168   ProxyErrorOverride    off
 169
 170   ProxyPass        /api http://localhost:8080 retry=0
 171   ProxyPassReverse /api http://localhost:8080
 172
 173 Make sure that in ``settings.local``::
 174
 175   USE_X_FORWARDED_HOST = True
 176
 177 Configure and run::
 178
 179   /etc/init.d/gunicorn restart
 180   a2enmod proxy
 181   a2enmod proxy_http
 182   /etc/init.d/apache2 restart
 183
 184 If experiencing timeout problems, try adding to ``/etc/gunicorn.d/pithos``::
 185
 186         ...
 187         '--timeout=43200',
 188         ...
 189
 190 Shibboleth Setup
 191 ----------------
 192
 193 Install package::
 194
 195   apt-get install libapache2-mod-shib2
 196
 197 Setup the files in ``/etc/shibboleth``.
 198
 199 Add in ``/etc/apache2/sites-available/pithos-ssl``::
 200
 201   ShibConfig /etc/shibboleth/shibboleth2.xml
 202   Alias      /shibboleth-sp /usr/share/shibboleth
 203
 204   <Location /api/im/login/shibboleth>
 205     AuthType shibboleth
 206     ShibRequireSession On
 207     ShibUseHeaders On
 208     require valid-user
 209   </Location>
 210
 211 Configure and run apache::
 212
 213   a2enmod shib2
 214   /etc/init.d/apache2 restart
 215   /etc/init.d/shibd restart
 216
 217 The following tokens should be available at the destination, after passing through the apache module::
 218
 219   eppn # eduPersonPrincipalName
 220   Shib-InetOrgPerson-givenName
 221   Shib-Person-surname
 222   Shib-Person-commonName
 223   Shib-InetOrgPerson-displayName
 224   Shib-EP-Affiliation
 225   Shib-Session-ID
 226
 227 MySQL Setup
 228 -----------
 229
 230 If using MySQL instead of SQLite for the database engine, consider the following.
 231
 232 Server side::
 233
 234   apt-get install mysql-server
 235
 236 Add in ``/etc/mysql/conf.d/pithos.cnf``::
 237
 238   [mysqld]
 239   sql-mode="NO_AUTO_VALUE_ON_ZERO"
 240
 241 Edit ``/etc/mysql/my.cnf`` to allow network connections and restart the server.
 242
 243 Create database and user::
 244
 245   CREATE DATABASE pithos CHARACTER SET utf8 COLLATE utf8_bin;
 246   GRANT ALL ON pithos.* TO pithos@localhost IDENTIFIED BY 'password';
 247   GRANT ALL ON pithos.* TO pithos@'%' IDENTIFIED BY 'password';
 248
 249 Client side::
 250
 251   apt-get install mysql-client
 252
 253 It helps to create a ``~/.my.cnf`` file, for automatically connecting to the server::
 254
 255   [client]
 256   user = pithos
 257   password = 'password'
 258   host = pithos-storage.dev.grnet.gr
 259
 260   [mysql]
 261   database = pithos
 262
 263 PostgreSQL Setup
 264 ----------------
 265
 266 If using PostgreSQL instead of SQLite for the database engine, consider the following.
 267
 268 Server side::
 269
 270   apt-get install postgresql
 271
 272 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.
 273
 274 Create database and user::
 275
 276   CREATE DATABASE pithos WITH ENCODING 'UTF8' LC_COLLATE='C' LC_CTYPE='C' TEMPLATE=template0;
 277   CREATE USER pithos WITH PASSWORD 'password';
 278   GRANT ALL PRIVILEGES ON DATABASE pithos TO pithos;
 279
 280 Client side::
 281
 282   apt-get install postgresql-client
 283
 284 It helps to create a ``~/.pgpass`` file, for automatically passing the password to the server::
 285
 286   pithos-storage.dev.grnet.gr:5432:pithos:pithos:password
 287
 288 Connect with::
 289
 290   psql -h pithos-storage.dev.grnet.gr -U pithos
 291