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-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 If experiencing timeout problems, try adding to ``/etc/gunicorn.d/pithos``::
 176
 177         ...
 178         '--timeout=43200',
 179         ...
 180
 181 Shibboleth Setup
 182 ----------------
 183
 184 Install package::
 185
 186   apt-get install libapache2-mod-shib2
 187
 188 Setup the files in ``/etc/shibboleth``.
 189
 190 Add in ``/etc/apache2/sites-available/pithos-ssl``::
 191
 192   ShibConfig /etc/shibboleth/shibboleth2.xml
 193   Alias      /shibboleth-sp /usr/share/shibboleth
 194
 195   <Location /api/im/login/shibboleth>
 196     AuthType shibboleth
 197     ShibRequireSession On
 198     ShibUseHeaders On
 199     require valid-user
 200   </Location>
 201
 202 Configure and run apache::
 203
 204   a2enmod shib2
 205   /etc/init.d/apache2 restart
 206   /etc/init.d/shibd restart
 207
 208 The following tokens should be available at the destination, after passing through the apache module::
 209
 210   eppn # eduPersonPrincipalName
 211   Shib-InetOrgPerson-givenName
 212   Shib-Person-surname
 213   Shib-Person-commonName
 214   Shib-InetOrgPerson-displayName
 215   Shib-EP-Affiliation
 216   Shib-Session-ID
 217
 218 MySQL Setup
 219 -----------
 220
 221 If using MySQL instead of SQLite for the database engine, consider the following.
 222
 223 Server side::
 224
 225   apt-get install mysql-server
 226
 227 Add in ``/etc/mysql/conf.d/pithos.cnf``::
 228
 229   [mysqld]
 230   sql-mode="NO_AUTO_VALUE_ON_ZERO"
 231
 232 Edit ``/etc/mysql/my.cnf`` to allow network connections and restart the server.
 233
 234 Create database and user::
 235
 236   CREATE DATABASE pithos CHARACTER SET utf8 COLLATE utf8_bin;
 237   GRANT ALL ON pithos.* TO pithos@localhost IDENTIFIED BY 'password';
 238   GRANT ALL ON pithos.* TO pithos@'%' IDENTIFIED BY 'password';
 239
 240 Client side::
 241
 242   apt-get install mysql-client
 243
 244 It helps to create a ``~/.my.cnf`` file, for automatically connecting to the server::
 245
 246   [client]
 247   user = pithos
 248   password = 'password'
 249   host = pithos-storage.dev.grnet.gr
 250
 251   [mysql]
 252   database = pithos
 253
 254 PostgreSQL Setup
 255 ----------------
 256
 257 If using PostgreSQL instead of SQLite for the database engine, consider the following.
 258
 259 Server side::
 260
 261   apt-get install postgresql
 262
 263 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.
 264
 265 Create database and user::
 266
 267   CREATE DATABASE pithos WITH ENCODING 'UTF8' LC_COLLATE='C' LC_CTYPE='C' TEMPLATE=template0;
 268   CREATE USER pithos WITH PASSWORD 'password';
 269   GRANT ALL PRIVILEGES ON DATABASE pithos TO pithos;
 270
 271 Client side::
 272
 273   apt-get install postgresql-client
 274
 275 It helps to create a ``~/.pgpass`` file, for automatically passing the password to the server::
 276
 277   pithos-storage.dev.grnet.gr:5432:pithos:pithos:password
 278
 279 Connect with::
 280
 281   psql -h pithos-storage.dev.grnet.gr -U pithos
 282