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