Update admin guide.

[pithos] / docs / source / adminguide.rst

diff --git a/docs/source/adminguide.rst b/docs/source/adminguide.rst
index 4151e60..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,6 +43,9 @@ 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,NE]
     RewriteRule ^/public(.*) /api/public$1 [PT,NE]
@@ -49,6 +53,8 @@ Edit ``/etc/apache2/sites-available/pithos`` (change the ``ServerName`` directiv
     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
     # WSGIProcessGroup pithos
@@ -58,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>
@@ -76,6 +92,9 @@ 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,NE]
     RewriteRule ^/public(.*) /api/public$1 [PT,NE]
@@ -83,6 +102,8 @@ Edit ``/etc/apache2/sites-available/pithos-ssl`` (assuming files in ``/etc/ssl/p
     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
@@ -101,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
@@ -114,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
 --------------
@@ -159,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
@@ -166,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
 ----------------