Documentation enhancements

ChangeLog

+===========
+1.0.2 RELEASE
+Documentation enhancements
+
 ===========
 1.0.1 RELEASE
 Minor fixes

_version.py

-VERSION = '1.0.1'
+VERSION = '1.0.2'
 
 if __name__ == "__main__":
     print VERSION

doc/source/conf.py

@@ -45,9 +45,9 @@ copyright = u'2014, Leonidas Poulopoulos (@leopoul), GRNET S.A'
 # built documents.
 #
 # The short X.Y version.
-version = '1.0.1'
+version = '1.0.2'
 # The full version, including alpha/beta/rc tags.
-release = '1.0.1'
+release = '1.0.2'
 
 # The language for content autogenerated by Sphinx. Refer to documentation
 # for a list of supported languages.

doc/source/index.rst

@@ -30,7 +30,7 @@ In GRNET's case the flowspec capable device is an EX4200.
 	Make sure your FoD server has ssh access to your flowspec device.
 
 .. attention::
-   Installation instructions assume a Debian Wheezy installation with Django 1.4
+   Installation instructions assume a clean Debian Wheezy with Django 1.4
    
 Contact
 =======

doc/source/install.rst

@@ -7,12 +7,18 @@ Installation
 
 Debian Wheezy (x64) - Django 1.4.x
 ==================================
-
 This guide assumes that installation is carried out in /srv/flowspy directory. If other directory is to be used, please change the corresponding configuration files. It is also assumed that the root user will perform every action.
 
+Upgrading from v<1.0.x
+----------------------
+If upgrading from flowspy version <1.0.x pay attention to settings.py changes. Also, do not forget to run::
+   
+   ./manage.py migrate
+   
+to catch-up with latest database changes.
+
 Required system packages
 ------------------------
-
 Update and install the required packages::
 
 	apt-get update
@@ -58,7 +64,6 @@ Get the required packages and install them
 
 Application configuration
 =========================
-
 Copy settings.py.dist to settings.py::
    
    cd flowspy
@@ -139,7 +144,6 @@ Now it is time to configure beanstalk, gunicorn, celery and apache.
 
 beanstalkd
 ----------
-
 Enable beanstalk by editting /etc/default/beanstalkd::
 
 	vim /etc/default/beanstalkd
@@ -152,8 +156,7 @@ Start beanstalkd::
 
 gunicorn.d
 ----------
-
-create and edit /etc/gunicorn.d/fod::
+Create and edit /etc/gunicorn.d/fod::
 
 	vim /etc/gunicorn.d/fod
 
@@ -166,18 +169,177 @@ FoD is served via gunicorn and is then proxied by Apache. If the above directory
            '--bind=127.0.0.1:8081',
            '--workers=1',
            '--worker-class=egg:gunicorn#gevent',
-           '--timeout=360',
+           '--timeout=30',
            '--log-level=debug',
-           '--log-file=/tmp/fod.log',
+           '--log-file=/var/log/flowspy.log',
        ),
    }
 
 
-celery.d
---------
-
+celeryd
+-------
 Celery is used over beanstalkd to apply firewall rules in a serial manner so that locks are avoided on the flowspec capable device. In our setup celery runs via django. That is why the python-django-celery package was installed.
 
+Create the celeryd daemon at /etc/init.d/celeryd **if it does not already exist**::
+
+   vim /etc/init.d/celeryd
+
+The configuration should be::
+
+   #!/bin/sh -e
+   # ============================================
+   #  celeryd - Starts the Celery worker daemon.
+   # ============================================
+   #
+   # :Usage: /etc/init.d/celeryd {start|stop|force-reload|restart|try-restart|status}
+   # :Configuration file: /etc/default/celeryd
+   #
+   # See http://docs.celeryq.org/en/latest/cookbook/daemonizing.html#init-script-celeryd
+   
+   
+   ### BEGIN INIT INFO
+   # Provides:          celeryd
+   # Required-Start:    $network $local_fs $remote_fs
+   # Required-Stop:     $network $local_fs $remote_fs
+   # Default-Start:     2 3 4 5
+   # Default-Stop:      0 1 6
+   # Short-Description: celery task worker daemon
+   # Description:       Starts the Celery worker daemon for a single project.
+   ### END INIT INFO
+   
+   #set -e
+   
+   DEFAULT_PID_FILE="/var/run/celery/%n.pid"
+   DEFAULT_LOG_FILE="/var/log/celery/%n.log"
+   DEFAULT_LOG_LEVEL="INFO"
+   DEFAULT_NODES="celery"
+   DEFAULT_CELERYD="-m celery.bin.celeryd_detach"
+   ENABLED="false"
+   
+   [ -r "$CELERY_DEFAULTS" ] && . "$CELERY_DEFAULTS"
+   
+   [ -r /etc/default/celeryd ] && . /etc/default/celeryd
+   
+   if [ "$ENABLED" != "true" ]; then
+       echo "celery daemon disabled - see /etc/default/celeryd."
+       exit 0
+   fi
+   
+   
+   CELERYD_PID_FILE=${CELERYD_PID_FILE:-${CELERYD_PIDFILE:-$DEFAULT_PID_FILE}}
+   CELERYD_LOG_FILE=${CELERYD_LOG_FILE:-${CELERYD_LOGFILE:-$DEFAULT_LOG_FILE}}
+   CELERYD_LOG_LEVEL=${CELERYD_LOG_LEVEL:-${CELERYD_LOGLEVEL:-$DEFAULT_LOG_LEVEL}}
+   CELERYD_MULTI=${CELERYD_MULTI:-"celeryd-multi"}
+   CELERYD=${CELERYD:-$DEFAULT_CELERYD}
+   CELERYCTL=${CELERYCTL:="celeryctl"}
+   CELERYD_NODES=${CELERYD_NODES:-$DEFAULT_NODES}
+   
+   export CELERY_LOADER
+   
+   if [ -n "$2" ]; then
+       CELERYD_OPTS="$CELERYD_OPTS $2"
+   fi
+   
+   CELERYD_LOG_DIR=`dirname $CELERYD_LOG_FILE`
+   CELERYD_PID_DIR=`dirname $CELERYD_PID_FILE`
+   if [ ! -d "$CELERYD_LOG_DIR" ]; then
+       mkdir -p $CELERYD_LOG_DIR
+   fi
+   if [ ! -d "$CELERYD_PID_DIR" ]; then
+       mkdir -p $CELERYD_PID_DIR
+   fi
+   
+   # Extra start-stop-daemon options, like user/group.
+   if [ -n "$CELERYD_USER" ]; then
+       DAEMON_OPTS="$DAEMON_OPTS --uid=$CELERYD_USER"
+       chown "$CELERYD_USER" $CELERYD_LOG_DIR $CELERYD_PID_DIR
+   fi
+   if [ -n "$CELERYD_GROUP" ]; then
+       DAEMON_OPTS="$DAEMON_OPTS --gid=$CELERYD_GROUP"
+       chgrp "$CELERYD_GROUP" $CELERYD_LOG_DIR $CELERYD_PID_DIR
+   fi
+   
+   if [ -n "$CELERYD_CHDIR" ]; then
+       DAEMON_OPTS="$DAEMON_OPTS --workdir=\"$CELERYD_CHDIR\""
+   fi
+   
+   
+   check_dev_null() {
+       if [ ! -c /dev/null ]; then
+           echo "/dev/null is not a character device!"
+           exit 1
+       fi
+   }
+   
+   
+   export PATH="${PATH:+$PATH:}/usr/sbin:/sbin"
+   
+   
+   stop_workers () {
+       $CELERYD_MULTI stop $CELERYD_NODES --pidfile="$CELERYD_PID_FILE"
+   }
+   
+   
+   start_workers () {
+       $CELERYD_MULTI start $CELERYD_NODES $DAEMON_OPTS        \
+                            --pidfile="$CELERYD_PID_FILE"      \
+                            --logfile="$CELERYD_LOG_FILE"      \
+                            --loglevel="$CELERYD_LOG_LEVEL"    \
+                            --cmd="$CELERYD"                   \
+                            $CELERYD_OPTS
+   }
+   
+   
+   restart_workers () {
+       $CELERYD_MULTI restart $CELERYD_NODES $DAEMON_OPTS      \
+                              --pidfile="$CELERYD_PID_FILE"    \
+                              --logfile="$CELERYD_LOG_FILE"    \
+                              --loglevel="$CELERYD_LOG_LEVEL"  \
+                              --cmd="$CELERYD"                 \
+                              $CELERYD_OPTS
+   }
+   
+   
+   
+   case "$1" in
+       start)
+           check_dev_null
+           start_workers
+       ;;
+   
+       stop)
+           check_dev_null
+           stop_workers
+       ;;
+   
+       reload|force-reload)
+           echo "Use restart"
+       ;;
+   
+       status)
+           $CELERYCTL status $CELERYCTL_OPTS
+       ;;
+   
+       restart)
+           check_dev_null
+           restart_workers
+       ;;
+   
+       try-restart)
+           check_dev_null
+           restart_workers
+       ;;
+   
+       *)
+           echo "Usage: /etc/init.d/celeryd {start|stop|restart|try-restart|kill}"
+           exit 1
+       ;;
+   esac
+   
+   exit 0
+
+celeryd configuration
+---------------------
 celeryd requires a /etc/default/celeryd file to be in place.
 Thus we are going to create this file (/etc/default/celeryd)::
 
@@ -203,22 +365,21 @@ Again if the directory conventions have been followed the file is (pay attention
    
    # Extra arguments to celeryd
    #CELERYD_OPTS="--time-limit=300 --concurrency=8"
-   CELERYD_OPTS="-E -B"
+   CELERYD_OPTS="-E -B --schedule=/var/run/celery/celerybeat-schedule"
    # Name of the celery config module.
    CELERY_CONFIG_MODULE="celeryconfig"
    
    # %n will be replaced with the nodename.
-   CELERYD_LOG_FILE="$CELERYD_CHDIR/celery_var/log/celery/%n.log"
-   CELERYD_PID_FILE="$CELERYD_CHDIR/celery_var/run/celery/%n.pid"
+   CELERYD_LOG_FILE="/var/log/celery/%n.log"
+   CELERYD_PID_FILE="/var/run/celery/%n.pid"
    
    # Workers should run as an unprivileged user.
-   CELERYD_USER="user"
-   CELERYD_GROUP="users"
+   CELERYD_USER="celery"
+   CELERYD_GROUP="celery"
    
    # Name of the projects settings module.
    export DJANGO_SETTINGS_MODULE="flowspy.settings"
 
-
 Apache
 ------
 Apache proxies gunicorn. Things are more flexible here as you may follow your own configuration and conventions. Create and edit /etc/apache2/sites-available/fod. You should set <server_name> and <admin_mail> along with your certificates. If under testing environment, you can use the provided snakeoil certs. If you do not intent to use Shibboleth delete or comment the corresponding configuration parts inside **Shibboleth configuration** ::
@@ -327,6 +488,16 @@ Restart, gunicorn and apache::
 
 	service gunicorn restart && service apache2 restart
 
+
+Propagate the flatpages
+=======================
+Inside the initial_data/fixtures_manual.xml file we have placed 4 flatpages (2 for Greek, 2 for English) with Information and Terms of Service about the service. 
+To import the flatpages, run from root folder::
+
+   python manage.py loaddata initial_data/fixtures_manual.xml
+
+
+
 Testing the platform
 ====================
 Log in to the admin interface via https://<hostname>/admin. Go to Peer ranges and add a new range (part of/or a complete subnet), eg. 10.20.0.0/19

flowspy/settings.py.dist

@@ -95,7 +95,7 @@ MEDIA_URL = ''
 # Don't put anything in this directory yourself; store your static files
 # in apps' "static/" subdirectories and in STATICFILES_DIRS.
 # Example: "/home/media/media.lawrence.com/static/"
-STATIC_ROOT = '/home/leopoul/projects/flowspy/static'
+STATIC_ROOT = '/path/to/projects/flowspy/static'
 
 # URL prefix for static files.
 # Example: "http://media.lawrence.com/static/"
@@ -180,7 +180,7 @@ INSTALLED_APPS = (
     'poller',
     'south',
     # Uncomment the next line to enable the admin:
-    # 'django.contrib.admin',
+    'django.contrib.admin',
     # Uncomment the next line to enable admin documentation:
     # 'django.contrib.admindocs',
     'djcelery',