Update admin guide.

[pithos] / docs / source / adminguide.rst

diff --git a/docs/source/adminguide.rst b/docs/source/adminguide.rst
index 3637431..4e8ae5e 100644 (file)
--- a/docs/source/adminguide.rst
+++ b/docs/source/adminguide.rst
@@ -8,7 +8,7 @@ Assuming a clean debian squeeze (stable) installation, use the following steps t
 
 Install packages::
 
-  apt-get install git python-django python-setuptools python-sphinx python-httplib2
+  apt-get install git python-django python-setuptools python-sphinx
   apt-get install python-sqlalchemy python-mysqldb python-psycopg2
   apt-get install apache2 libapache2-mod-wsgi
 
@@ -17,14 +17,15 @@ Get the source::
   cd /
   git clone https://code.grnet.gr/git/pithos
 
-Setup the files (choose where to store data in ``settings.py`` and change ``SECRET_KEY``)::
+Setup the files::
 
   cd /pithos/pithos
-  cp settings.py.dist settings.py
   python manage.py syncdb
   cd /pithos
   python setup.py build_sphinx
 
+It is advised that you create a ``settings.local`` file to place any configuration overrides (at least change ``SECRET_KEY``).
+
 Edit ``/etc/apache2/sites-available/pithos`` (change the ``ServerName`` directive)::
 
   <VirtualHost *:80>
@@ -42,10 +43,17 @@ Edit ``/etc/apache2/sites-available/pithos`` (change the ``ServerName`` directiv
         Allow from all
     </Directory>
 
+    SetEnv no-gzip
+    SetEnv dont-vary
+
     RewriteEngine On
-    RewriteRule ^/v(.*) /api/v$1 [PT]
-    RewriteRule ^/public(.*) /api/public$1 [PT]
-    RewriteRule ^/im(.*) https://%{HTTP_HOST}%{REQUEST_URI}
+    RewriteRule ^/v(.*) /api/v$1 [PT,NE]
+    RewriteRule ^/public(.*) /api/public$1 [PT,NE]
+    RewriteRule ^/tools(.*) /api/ui$1 [PT,NE]
+    RewriteRule ^/im(.*) https://%{HTTP_HOST}%{REQUEST_URI} [NE]
+    RewriteRule ^/login(.*) https://%{HTTP_HOST}%{REQUEST_URI} [NE]
+
+    RequestHeader set X-Forwarded-Protocol "http"
 
     WSGIScriptAlias /api /pithos/pithos/wsgi/pithos.wsgi
     # WSGIDaemonProcess pithos
@@ -56,6 +64,16 @@ Edit ``/etc/apache2/sites-available/pithos`` (change the ``ServerName`` directiv
     CustomLog ${APACHE_LOG_DIR}/pithos.access.log combined
   </VirtualHost>
 
+To disable non-SSL connections, ``/etc/apache2/sites-available/pithos`` should be::
+
+  <VirtualHost *:80>
+    ServerAdmin webmaster@pithos.dev.grnet.gr
+    ServerName pithos.dev.grnet.gr
+
+    RewriteEngine On
+    RewriteRule (.*) https://%{HTTP_HOST}%{REQUEST_URI}
+  </VirtualHost>
+
 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)::
 
   <IfModule mod_ssl.c>
@@ -74,25 +92,22 @@ Edit ``/etc/apache2/sites-available/pithos-ssl`` (assuming files in ``/etc/ssl/p
         Allow from all
     </Directory>
 
+    SetEnv no-gzip
+    SetEnv dont-vary
+
     RewriteEngine On
-    RewriteRule ^/v(.*) /api/v$1 [PT]
-    RewriteRule ^/public(.*) /api/public$1 [PT]
-    RewriteRule ^/im(.*) /api/im$1 [PT]
+    RewriteRule ^/v(.*) /api/v$1 [PT,NE]
+    RewriteRule ^/public(.*) /api/public$1 [PT,NE]
+    RewriteRule ^/tools(.*) /api/ui$1 [PT,NE]
+    RewriteRule ^/im(.*) /api/im$1 [PT,NE]
+    RewriteRule ^/login(.*) /api/im/login/dummy$1 [PT,NE]
+
+    RequestHeader set X-Forwarded-Protocol "https"
 
     WSGIScriptAlias /api /pithos/pithos/wsgi/pithos.wsgi
     # WSGIDaemonProcess pithos
     # WSGIProcessGroup pithos
 
-    ShibConfig /etc/shibboleth/shibboleth2.xml
-    Alias      /shibboleth-sp /usr/share/shibboleth 
-
-    <Location /api/im/login/shibboleth>
-        AuthType shibboleth
-        ShibRequireSession On
-        ShibUseHeaders On
-        require valid-user
-    </Location>
-
     LogLevel warn
     ErrorLog ${APACHE_LOG_DIR}/pithos.error.log
     CustomLog ${APACHE_LOG_DIR}/pithos.access.log combined
@@ -107,6 +122,15 @@ Add in ``/etc/apache2/mods-available/wsgi.conf``::
 
   WSGIChunkedRequest On
 
+Make sure the data folder is writable by the web server user::
+
+  chown -R www-data:www-data /pithos/pithos/data
+
+If using an SQLite database, the same goes for the database file and the containing folder::
+
+  chown www-data:www-data /pithos/pithos/
+  chown www-data:www-data /pithos/pithos/backend.db
+
 Configure and run apache::
 
   a2enmod ssl
@@ -120,7 +144,7 @@ Configure and run apache::
 
 Useful alias to add in ``~/.bashrc``::
 
-  alias pithos-sync='cd /pithos && git pull && python setup.py build_sphinx && /etc/init.d/apache2 restart'
+  alias sync-pithos='cd /pithos && git pull && python setup.py build_sphinx && /etc/init.d/apache2 restart'
 
 Gunicorn Setup
 --------------
@@ -165,6 +189,10 @@ Replace the ``WSGI*`` directives in ``/etc/apache2/sites-available/pithos`` and
   ProxyPass        /api http://localhost:8080 retry=0
   ProxyPassReverse /api http://localhost:8080
 
+Make sure that in ``settings.local``::
+
+  USE_X_FORWARDED_HOST = True
+
 Configure and run::
 
   /etc/init.d/gunicorn restart
@@ -172,6 +200,12 @@ Configure and run::
   a2enmod proxy_http
   /etc/init.d/apache2 restart
 
+If experiencing timeout problems, try adding to ``/etc/gunicorn.d/pithos``::
+
+        ...
+        '--timeout=43200',
+        ...
+
 Shibboleth Setup
 ----------------
 
@@ -186,7 +220,7 @@ Add in ``/etc/apache2/sites-available/pithos-ssl``::
   ShibConfig /etc/shibboleth/shibboleth2.xml
   Alias      /shibboleth-sp /usr/share/shibboleth 
 
-  <Location /api/login>
+  <Location /api/im/login/shibboleth>
     AuthType shibboleth
     ShibRequireSession On
     ShibUseHeaders On