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