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 Make sure the data folder is writable by the web server user::
 116
 117   chown -R www-data:www-data /pithos/pithos/data
 118
 119 If using an SQLite database, the same goes for the database file and the containing folder::
 120
 121   chown www-data:www-data /pithos/pithos/
 122   chown www-data:www-data /pithos/pithos/backend.db
 123
 124 Configure and run apache::
 125
 126   a2enmod ssl
 127   a2enmod rewrite
 128   a2dissite default
 129   a2ensite pithos
 130   a2ensite pithos-ssl
 131   mkdir /var/www/pithos
 132   mkdir /var/www/pithos_web_client
 133   /etc/init.d/apache2 restart
 134
 135 Useful alias to add in ``~/.bashrc``::
 136
 137   alias sync-pithos='cd /pithos && git pull && python setup.py build_sphinx && /etc/init.d/apache2 restart'
 138
 139 Gunicorn Setup
 140 --------------
 141
 142 Add in ``/etc/apt/sources.list``::
 143
 144   deb http://backports.debian.org/debian-backports squeeze-backports main
 145
 146 Then::
 147
 148   apt-get update
 149   apt-get -t squeeze-backports install gunicorn
 150   apt-get -t squeeze-backports install python-gevent
 151
 152 Create ``/etc/gunicorn.d/pithos``::
 153
 154   CONFIG = {
 155    'mode': 'django',
 156    'working_dir': '/pithos/pithos',
 157    'user': 'www-data',
 158    'group': 'www-data',
 159    'args': (
 160         '--bind=[::]:8080',
 161         '--worker-class=egg:gunicorn#gevent',
 162         '--workers=4',
 163         '--log-level=debug',
 164         '/pithos/pithos/settings.py',
 165    ),
 166   }
 167
 168 Replace the ``WSGI*`` directives in ``/etc/apache2/sites-available/pithos`` and ``/etc/apache2/sites-available/pithos-ssl`` with::
 169
 170   <Proxy *>
 171     Order allow,deny
 172     Allow from all
 173   </Proxy>
 174
 175   SetEnv                proxy-sendchunked
 176   SSLProxyEngine        off
 177   ProxyErrorOverride    off
 178
 179   ProxyPass        /api http://localhost:8080 retry=0
 180   ProxyPassReverse /api http://localhost:8080
 181
 182 Make sure that in ``settings.local``::
 183
 184   USE_X_FORWARDED_HOST = True
 185
 186 Configure and run::
 187
 188   /etc/init.d/gunicorn restart
 189   a2enmod proxy
 190   a2enmod proxy_http
 191   /etc/init.d/apache2 restart
 192
 193 If experiencing timeout problems, try adding to ``/etc/gunicorn.d/pithos``::
 194
 195         ...
 196         '--timeout=43200',
 197         ...
 198
 199 Shibboleth Setup
 200 ----------------
 201
 202 Install package::
 203
 204   apt-get install libapache2-mod-shib2
 205
 206 Setup the files in ``/etc/shibboleth``.
 207
 208 Add in ``/etc/apache2/sites-available/pithos-ssl``::
 209
 210   ShibConfig /etc/shibboleth/shibboleth2.xml
 211   Alias      /shibboleth-sp /usr/share/shibboleth
 212
 213   <Location /api/im/login/shibboleth>
 214     AuthType shibboleth
 215     ShibRequireSession On
 216     ShibUseHeaders On
 217     require valid-user
 218   </Location>
 219
 220 Configure and run apache::
 221
 222   a2enmod shib2
 223   /etc/init.d/apache2 restart
 224   /etc/init.d/shibd restart
 225
 226 The following tokens should be available at the destination, after passing through the apache module::
 227
 228   eppn # eduPersonPrincipalName
 229   Shib-InetOrgPerson-givenName
 230   Shib-Person-surname
 231   Shib-Person-commonName
 232   Shib-InetOrgPerson-displayName
 233   Shib-EP-Affiliation
 234   Shib-Session-ID
 235
 236 MySQL Setup
 237 -----------
 238
 239 If using MySQL instead of SQLite for the database engine, consider the following.
 240
 241 Server side::
 242
 243   apt-get install mysql-server
 244
 245 Add in ``/etc/mysql/conf.d/pithos.cnf``::
 246
 247   [mysqld]
 248   sql-mode="NO_AUTO_VALUE_ON_ZERO"
 249
 250 Edit ``/etc/mysql/my.cnf`` to allow network connections and restart the server.
 251
 252 Create database and user::
 253
 254   CREATE DATABASE pithos CHARACTER SET utf8 COLLATE utf8_bin;
 255   GRANT ALL ON pithos.* TO pithos@localhost IDENTIFIED BY 'password';
 256   GRANT ALL ON pithos.* TO pithos@'%' IDENTIFIED BY 'password';
 257
 258 Client side::
 259
 260   apt-get install mysql-client
 261
 262 It helps to create a ``~/.my.cnf`` file, for automatically connecting to the server::
 263
 264   [client]
 265   user = pithos
 266   password = 'password'
 267   host = pithos-storage.dev.grnet.gr
 268
 269   [mysql]
 270   database = pithos
 271
 272 PostgreSQL Setup
 273 ----------------
 274
 275 If using PostgreSQL instead of SQLite for the database engine, consider the following.
 276
 277 Server side::
 278
 279   apt-get install postgresql
 280
 281 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.
 282
 283 Create database and user::
 284
 285   CREATE DATABASE pithos WITH ENCODING 'UTF8' LC_COLLATE='C' LC_CTYPE='C' TEMPLATE=template0;
 286   CREATE USER pithos WITH PASSWORD 'password';
 287   GRANT ALL PRIVILEGES ON DATABASE pithos TO pithos;
 288
 289 Client side::
 290
 291   apt-get install postgresql-client
 292
 293 It helps to create a ``~/.pgpass`` file, for automatically passing the password to the server::
 294
 295   pithos-storage.dev.grnet.gr:5432:pithos:pithos:password
 296
 297 Connect with::
 298
 299   psql -h pithos-storage.dev.grnet.gr -U pithos
 300