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 (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 ^/login(.*) https://%{HTTP_HOST}%{REQUEST_URI}
  49     RewriteRule ^/admin(.*) https://%{HTTP_HOST}%{REQUEST_URI}
  50
  51     WSGIScriptAlias /api /pithos/pithos/wsgi/pithos.wsgi
  52     # WSGIDaemonProcess pithos
  53     # WSGIProcessGroup pithos
  54
  55     LogLevel warn
  56     ErrorLog ${APACHE_LOG_DIR}/pithos.error.log
  57     CustomLog ${APACHE_LOG_DIR}/pithos.access.log combined
  58   </VirtualHost>
  59
  60 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)::
  61
  62   <IfModule mod_ssl.c>
  63   <VirtualHost _default_:443>
  64     ServerAdmin webmaster@pithos.dev.grnet.gr
  65     ServerName pithos.dev.grnet.gr
  66
  67     DocumentRoot /pithos/htdocs
  68     Alias /ui "/var/www/pithos_web_client"
  69     Alias /docs "/pithos/docs/build/html"
  70
  71     <Directory />
  72         Options Indexes FollowSymLinks
  73         AllowOverride None
  74         Order allow,deny
  75         Allow from all
  76     </Directory>
  77
  78     RewriteEngine On
  79     RewriteRule ^/v(.*) /api/v$1 [PT]
  80     RewriteRule ^/public(.*) /api/public$1 [PT]
  81     RewriteRule ^/login(.*) /api/login$1 [PT]
  82     RewriteRule ^/admin(.*) /api/admin$1 [PT]
  83
  84     WSGIScriptAlias /api /pithos/pithos/wsgi/pithos.wsgi
  85     # WSGIDaemonProcess pithos
  86     # WSGIProcessGroup pithos
  87
  88     ShibConfig /etc/shibboleth/shibboleth2.xml
  89     Alias      /shibboleth-sp /usr/share/shibboleth
  90
  91     <Location /api/login>
  92         AuthType shibboleth
  93         ShibRequireSession On
  94         ShibUseHeaders On
  95         require valid-user
  96     </Location>
  97
  98     LogLevel warn
  99     ErrorLog ${APACHE_LOG_DIR}/pithos.error.log
 100     CustomLog ${APACHE_LOG_DIR}/pithos.access.log combined
 101
 102     SSLEngine on
 103     SSLCertificateFile    /etc/ssl/certs/pithos.dev.grnet.gr.crt
 104     SSLCertificateKeyFile /etc/ssl/private/pithos.dev.grnet.gr.key
 105   </VirtualHost>
 106   </IfModule>
 107
 108 Add in ``/etc/apache2/mods-available/wsgi.conf``::
 109
 110   WSGIChunkedRequest On
 111
 112 Configure and run apache::
 113
 114   a2enmod ssl
 115   a2enmod rewrite
 116   a2dissite default
 117   a2ensite pithos
 118   a2ensite pithos-ssl
 119   mkdir /var/www/pithos
 120   mkdir /var/www/pithos_web_client
 121   /etc/init.d/apache2 restart
 122
 123 Useful alias to add in ``~/.bashrc``::
 124
 125   alias pithos-sync='cd /pithos && git pull && python setup.py build_sphinx && /etc/init.d/apache2 restart'
 126
 127 Shibboleth Setup
 128 ----------------
 129
 130 Install package::
 131
 132   apt-get install libapache2-mod-shib2
 133
 134 Setup the files in ``/etc/shibboleth``.
 135
 136 Add in ``/etc/apache2/sites-available/pithos-ssl``::
 137
 138         ShibConfig /etc/shibboleth/shibboleth2.xml
 139         Alias      /shibboleth-sp /usr/share/shibboleth
 140
 141         <Location /api/login>
 142                 AuthType shibboleth
 143                 ShibRequireSession On
 144                 ShibUseHeaders On
 145                 require valid-user
 146         </Location>
 147
 148 Configure and run apache::
 149
 150   a2enmod shib2
 151   /etc/init.d/apache2 restart
 152   /etc/init.d/shibd restart
 153
 154 The following tokens should be available at the destination, after passing through the apache module::
 155
 156   SHIB_EPPN = "eppn" # eduPersonPrincipalName
 157   SHIB_NAME = "Shib-InetOrgPerson-givenName"
 158   SHIB_SURNAME = "Shib-Person-surname"
 159   SHIB_CN = "Shib-Person-commonName"
 160   SHIB_DISPLAYNAME = "Shib-InetOrgPerson-displayName"
 161   SHIB_EP_AFFILIATION = "Shib-EP-Affiliation"
 162   SHIB_SESSION_ID = "Shib-Session-ID"
 163
 164 MySQL Setup
 165 -----------
 166
 167 If using MySQL instead of SQLite for the database engine, consider the following.
 168
 169 Server side::
 170
 171   apt-get install mysql-server
 172
 173 Add in ``/etc/mysql/conf.d/pithos.cnf``::
 174
 175   [mysqld]
 176   sql-mode="NO_AUTO_VALUE_ON_ZERO"
 177
 178 Edit ``/etc/mysql/my.cnf`` to allow network connections and restart the server.
 179
 180 Create database and user::
 181
 182   CREATE DATABASE pithos CHARACTER SET utf8 COLLATE utf8_bin;
 183   GRANT ALL ON pithos.* TO pithos@localhost IDENTIFIED BY 'password';
 184   GRANT ALL ON pithos.* TO pithos@'%' IDENTIFIED BY 'password';
 185
 186 Client side::
 187
 188   apt-get install mysql-client
 189
 190 It helps to create a ``~/.my.cnf`` file, for automatically connecting to the server::
 191
 192   [client]
 193   user = pithos
 194   password = 'password'
 195   host = pithos-storage.dev.grnet.gr
 196
 197   [mysql]
 198   database = pithos
 199
 200 PostgreSQL Setup
 201 ----------------
 202
 203 If using PostgreSQL instead of SQLite for the database engine, consider the following.
 204
 205 Server side::
 206
 207   apt-get install postgresql
 208
 209 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.
 210
 211 Create database and user::
 212
 213   CREATE DATABASE pithos WITH ENCODING 'UTF8' LC_COLLATE='C' LC_CTYPE='C' TEMPLATE=template0;
 214   CREATE USER pithos WITH PASSWORD 'password';
 215   GRANT ALL PRIVILEGES ON DATABASE pithos TO pithos;
 216
 217 Client side::
 218
 219   apt-get install postgresql-client
 220
 221 It helps to create a ``~/.pgpass`` file, for automatically passing the password to the server::
 222
 223   pithos-storage.dev.grnet.gr:5432:pithos:pithos:password
 224
 225 Connect with::
 226
 227   psql -h pithos-storage.dev.grnet.gr -U pithos
 228