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