Commit e0184c36 authored by Leonidas Poulopoulos's avatar Leonidas Poulopoulos
Browse files

Added Sphinx documentation. Closes #3236

parent 7ee6a39a
# -*- coding: utf-8 -*-
#
# DjNRO (eduroam) documentation build configuration file
#
# This file is execfile()d with the current directory set to its containing dir.
#
# Note that not all possible configuration values are present in this
# autogenerated file.
#
# All configuration values have a default; values that are commented out
# serve to show the default.
import sys, os
# Optional. Use a shorter name to conserve nav. bar space.
# If extensions (or modules to document with autodoc) are in another directory,
# add these directories to sys.path here. If the directory is relative to the
# documentation root, use os.path.abspath to make it absolute, like shown here.
# -- General configuration -----------------------------------------------------
# If your documentation needs a minimal Sphinx version, state it here.
#needs_sphinx = "1.0"
# Add any Sphinx extension module names here, as strings. They can be extensions
# coming with Sphinx (named "sphinx.ext.*") or your custom ones.
extensions = [
"sphinx.ext.todo",
"sphinx.ext.graphviz",
'sphinx.ext.autodoc', 'sphinx.ext.doctest', 'sphinx.ext.intersphinx', 'sphinx.ext.coverage', 'sphinx.ext.pngmath', 'sphinx.ext.ifconfig', 'sphinx.ext.autosummary'
]
# Add any paths that contain templates here, relative to this directory.
#templates_path = ["_templates"]
# The suffix of source filenames.
source_suffix = ".rst"
# The encoding of source files.
source_encoding = "utf-8"
# The master toctree document.
master_doc = "index"
# General information about the project.
project = u"DjNRO"
copyright = u"2013, GRNET S.A. - Designed and developed by Leonidas Poulopoulos and Zenon Mousmoulas - GRNET NOC"
# The version info for the project you're documenting, acts as replacement for
# |version| and |release|, also used in various other places throughout the
# built documents.
#
# These next two will be passed via the command line, see the makefile
# The short X.Y version
#version = "0.4"
# The full version, including alpha/beta/rc tags.
#release = "pre-release"
# The language for content autogenerated by Sphinx. Refer to documentation
# for a list of supported languages.
language = "en"
# There are two options for replacing |today|: either, you set today to some
# non-false value, then it is used:
#today = ""
# Else, today_fmt is used as the format for a strftime call.
#today_fmt = "%B %d, %Y"
# List of documents that shouldn't be included in the build.
#unused_docs = []
# List of directories, relative to source directory, that shouldn't be searched
# for source files.
#exclude_trees = [
# "_build",
# "api",
# ]
# The reST default role (used for this markup: `text`) to use for all documents.
#default_role = None
# If true, "()" will be appended to :func: etc. cross-reference text.
#add_function_parentheses = True
# If true, the current module name will be prepended to all description
# unit titles (such as .. function::).
#add_module_names = True
# If true, sectionauthor and moduleauthor directives will be shown in the
# output. They are ignored by default.
#show_authors = False
# The name of the Pygments (syntax highlighting) style to use.
pygments_style = "sphinx"
# A list of ignored prefixes for module index sorting.
#modindex_common_prefix = ['iooclient.']
# -- Options for HTML output ---------------------------------------------------
# The theme to use for HTML and HTML Help pages. See the documentation for
# a list of builtin themes.
html_theme = "sphinxdoc"
# Theme options are theme-specific and customize the look and feel of a theme
# further. For a list of options available for each theme, see the
# documentation.
#html_theme_options = {}
# Add any paths that contain custom themes here, relative to this directory.
#html_theme_path = []
# The name for this set of Sphinx documents. If None, it defaults to
# "<project> v<release> documentation".
#html_title = None
# A shorter title for the navigation bar. Default is the same as html_title.
#html_short_title = None
# The name of an image file (relative to this directory) to place at the top
# of the sidebar.
html_logo = "logo.png"
# The name of an image file (within the static path) to use as favicon of the
# docs. This file should be a Windows icon file (.ico) being 16x16 or 32x32
# pixels large.
#html_favicon = None
# Add any paths that contain custom static files (such as style sheets) here,
# relative to this directory. They are copied after the builtin static files,
# so a file named "default.css" will overwrite the builtin "default.css".
html_static_path = ['_static']
# If not "", a "Last updated on:" timestamp is inserted at every page bottom,
# using the given strftime format.
#html_last_updated_fmt = "%b %d, %Y"
# If true, SmartyPants will be used to convert quotes and dashes to
# typographically correct entities.
#html_use_smartypants = True
# Custom sidebar templates, maps document names to template names.
#html_sidebars = {}
# Additional templates that should be rendered to pages, maps page names to
# template names.
#html_additional_pages = {}
# If false, no module index is generated.
html_use_modindex = False
# If false, no index is generated.
html_use_index = False
# If true, the index is split into individual pages for each letter.
#html_split_index = False
# If true, links to the reST sources are added to the pages.
#html_show_sourcelink = True
# If true, "Created using Sphinx" is shown in the HTML footer. Default is True.
#html_show_sphinx = True
# If true, "(C) Copyright ..." is shown in the HTML footer. Default is True.
#html_show_copyright = True
# If true, an OpenSearch description file will be output, and all pages will
# contain a <link> tag referring to it. The value of this option must be the
# base URL from which the finished HTML is served.
#html_use_opensearch = ""
# If nonempty, this is the file name suffix for HTML files (e.g. ".xhtml").
#html_file_suffix = ""
# Output file base name for HTML help builder.
htmlhelp_basename = "eduroamdoc"
intersphinx_mapping = {'http://docs.python.org/': None}
autoclass_content = 'both'
DjNRO: Django National Roaming Operator or how to manage your eduroam database
=================================================================================
DjNRO = Django + NRO
About
--------------------------
In the `eduroam <http://www.eduroam.org>`_ world, NRO stands for National Roaming Operator.
Maintaining and managing a local eduroam database is quite an important responsibility of an eduroam NRO.
eduroam.org periodically polls and gathers information from all participating domains.
Information is provided upstream, in a structured way (XML format) and consists of participating institutions' data, location data along with monitoring data - though provisioning of monitoring data has been superseeded by the f-Ticks mechanism.
The source of information should be the local eduroam database. So, changes to the database should be reflected to the XML files.
New eduroam locations, changes in contacts and information about each location should be up-to-date so as to ease the eduroam usage and assist eduroam users whenever they need support.
DjNRO is a Django platform that eases the management process of a National Roaming Operator. DjNRO complies with the `eduroam database <http://monitor.eduroam.org/database.php>`_ and the eduroam XSDs.
Thus, apart from domain management, it can generate the necessary xml files for eduroam.org monitoring.
DjNRO is more than keeping eduroam.org updated with data.
In essence it is a distributed management application. It is distributed in the sense that information about each institution locations and services is kept up-to-date by each local eduroam administrator. Keeping in pace with eduroam's federated nature, our implementation uses federated authentication/authorisation mechanisms, namely Shibboleth.
In case Shibboleth is not an option for an institution, a social media auth mechanism comes in handy. The local institution eduroam administrators can become DjNRO admins. Local eduroam administrators register to the platform via Shibboleth or social media auth. The NRO's responsibility is to activate their accounts.
From then on they can manage their eduroam locations, contact points and institution information. The administrative interface especially the locations management part, is heavily implemented with Google Maps. This makes editing easier, faster and accurate.
Installation and customization is fairly easy and is described in the following sections.
Currently the source code is availiable at code.grnet.gr and can be cloned via git::
git clone https://code.grnet.gr/git/eduroam
The Greek eduroam webpage is a living example of DjNRO: `eduroam|gr <http://www.eduroam.gr>`_
Features
------------------
* Allow your local eduroam admins to edit their local eduroam data (AP locations, server params, etc)
* Visualize the information via Google Maps
* Eduroam world maps overview via daily update on eduroam.org KML file
* **PLUS**: Find your closest eduroam in the world
Bootstrap CSS framework with responsive design makes it work on every device
Requirements
---------------
.. toctree::
require
Installation
-----------------------
.. toctree::
install
.. _install-label:
Installation/Configuration
=========================================================================
.. contents::
Assuming that you have installed all the required packages as described in :ref:`require-label` you can install the eduroam platform application.
Currently the source code is availiable at code.grnet.gr and can be cloned via git::
git clone https://code.grnet.gr/git/eduroam
As with the majority of Django projects, settings.py has to be properly configured and then comes the population of the database.
* Copy the urls.py.dist to urls.py
* Copy the settings.py.dist to settings.py
* Copy the apache/django.wsgi.dist to apache/django.wsgi and *edit* according to your needs.
Project Settings (settings.py)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
The following variables/settings need to be altered or set:
Set Admin contacts::
ADMINS = (
('Admin', 'admin@example.com'),
)
Set the database connection params::
DATABASES = {
...
}
Set your timezone and Languages::
TIME_ZONE = 'Europe/Athens'
LANGUAGES = (
('el', _('Greek')),
('en', _('English')),
)
Set your static url::
STATIC_URL = '/example/static'
Django social auth needs changes in the Authentication Backends depending on which social auth you want to enable::
AUTHENTICATION_BACKENDS = (
'eduroam.djangobackends.shibauthBackend.shibauthBackend',
...
'django.contrib.auth.backends.ModelBackend',
)
Set your template dirs::
TEMPLATE_DIRS = (
"/example/templates"
# Put strings here, like "/home/html/django_templates" or "C:/www/django/templates".
# Always use forward slashes, even on Windows.
# Don't forget to use absolute paths, not relative paths.
)
As the application includes a "Nearest Eduroam" functionality, world eduroam points are harvested via the eduroam.org kml file::
EDUROAM_KML_URL = 'http://monitor.eduroam.org/kml/all.kml'
Depending on your AAI policy set an appropriate authEntitlement
SHIB_AUTH_ENTITLEMENT = 'urn:mace:example.com:pki:user'
Mail server parameters::
SERVER_EMAIL = "Example domain eduroam Service <noreply@example.com>"
EMAIL_SUBJECT_PREFIX = "[eduroam] "
NRO contact mails::
NOTIFY_ADMIN_MAILS = ["mail1@example.com", "mail2@example.com"]
Set your cache backend (if you want to use one)::
CACHE_BACKEND = 'memcached://127.0.0.1:11211/?timeout=5184000'
NRO specific parameters. Affect html templates::
# Frontend country specific vars, eg. Greece
NRO_COUNTRY_NAME = _('My Country')
# Variable used by context_processor to display the "eduroam | <country_code>" in base.html
NRO_COUNTRY_CODE = 'gr'
# main domain url used in right top icon, eg. http://www.grnet.gr
NRO_DOMAIN_MAIN_URL = "http://www.example.com"
# developer info for footer
NRO_DEV_BY_DICT = {"name": "EXAMPLE DEV TEAM", "url": "http://devteam.example.com"}
#NRO social media contact (Use: // to preserve https)
NRO_DEV_SOCIAL_MEDIA_CONTACT = [
{"url":"//soc.media.url", "icon":"icon.png", "name":"NAME1(eg. Facebook)"},
{"url":"//soc.media.url", "icon":"icon.png", "name":"NAME2(eg. Twitter)"},
]
# map center (lat, lng)
MAP_CENTER = (36.97, 23.71)
#Helpdesk, used in base.html:
NRO_DOMAIN_HELPDESK_DICT = {"name": _("Domain Helpdesk"), 'email':'helpdesk@example.com', 'phone': '12324567890', 'uri': 'helpdesk.example.com'}
Set the Realm country for REALM model::
#Countries for Realm model:
REALM_COUNTRIES = (
('country_2letters', 'Country' ),
)
Shibboleth attribute MAP according to your AAI policy::
#Shibboleth attribute map
SHIB_USERNAME = ['HTTP_EPPN']
SHIB_MAIL = ['mail', 'HTTP_MAIL', 'HTTP_SHIB_INETORGPERSON_MAIL']
SHIB_FIRSTNAME = ['HTTP_SHIB_INETORGPERSON_GIVENNAME']
SHIB_LASTNAME = ['HTTP_SHIB_PERSON_SURNAME']
SHIB_ENTITLEMENT = ['HTTP_SHIB_EP_ENTITLEMENT']
Django Social Auth parameters::
TWITTER_CONSUMER_KEY = ''
TWITTER_CONSUMER_SECRET = ''
FACEBOOK_APP_ID = ''
FACEBOOK_API_SECRET = ''
LINKEDIN_CONSUMER_KEY = ''
LINKEDIN_CONSUMER_SECRET = ''
LINKEDIN_SCOPE = ['r_basicprofile', 'r_emailaddress']
LINKEDIN_EXTRA_FIELD_SELECTORS = ['email-address', 'headline', 'industry']
LINKEDIN_EXTRA_DATA = [('id', 'id'),
('first-name', 'first_name'),
('last-name', 'last_name'),
('email-address', 'email_address'),
('headline', 'headline'),
('industry', 'industry')]
YAHOO_CONSUMER_KEY = ''
YAHOO_CONSUMER_SECRET = ''
GOOGLE_SREG_EXTRA_DATA = []
SOCIAL_AUTH_FORCE_POST_DISCONNECT = True
FACEBOOK_EXTENDED_PERMISSIONS = ['email']
SOCIAL_AUTH_LOGIN_REDIRECT_URL = '/manage/'
LOGIN_REDIRECT_URL = '/manage/'
SOCIAL_AUTH_INACTIVE_USER_URL = '/manage/'
SOCIAL_AUTH_FORCE_POST_DISCONNECT = True
SOCIAL_AUTH_REDIRECT_IS_HTTPS = True
SOCIAL_AUTH_CREATE_USERS = True
SOCIAL_AUTH_FORCE_RANDOM_USERNAME = False
SOCIAL_AUTH_SANITIZE_REDIRECTS = False
SOCIAL_AUTH_PIPELINE = (
'social_auth.backends.pipeline.social.social_auth_user',
'social_auth.backends.pipeline.user.get_username',
'social_auth.backends.pipeline.user.create_user',
'social_auth.backends.pipeline.social.associate_user',
'social_auth.backends.pipeline.social.load_extra_data',
'social_auth.backends.pipeline.user.update_user_details',
)
Database Sync
^^^^^^^^^^^^^^^^
Once you are done with settings.py run::
./manage.py syncdb
Create a superuser, it comes in handy. And then run south migration to complete::
./manage.py migrate
Now you should have a clean database with all the tables created.
Running the server
^^^^^^^^^^^^^^^^^^^
We suggest going via Apache with mod_wsgi. Below is an example configuration::
WSGIDaemonProcess eduroam processes=3 threads=20 display-name=%{GROUP}
WSGIProcessGroup eduroam
...
<VirtualHost *:443>
ServerName example.com
ServerAdmin admin@example.com
ServerSignature On
SSLEngine on
SSLCertificateFile ...
SSLCertificateChainFile ...
SSLCertificateKeyFile ...
# Shibboleth SP configuration
ShibConfig /etc/shibboleth/shibboleth2.xml
Alias /shibboleth-sp /usr/share/shibboleth
# Integration of Shibboleth into Django app:
<Location /login>
AuthType shibboleth
ShibRequireSession On
ShibUseHeaders On
require valid-user
</Location>
<Location /Shibboleth.sso>
SetHandler shib
</Location>
Alias /static /path/to/eduroam/static
WSGIScriptAlias / /path/to/eduroam/apache/django.wsgi
</VirtualHost>
*Info*: It is strongly suggested to allow access to /admin|overview|alt-login *ONLY* from trusted subnets.
Once you are done, restart apache.
Initial Data
^^^^^^^^^^^^^^^^
What you really need in the first place is a Realm record along with one or more contacts related to that Realm. Go via the Admin interface, and add a Realm (remember to have set the REALM_COUNTRIES in settings.py).
The approach in the application is that the NRO sets the environment for the local eduroam admins. Towards that direction, the NRO has to insert the initial data for his/her clients/institutions in the *Institutions* Model
Next Steps (Set your Logo)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
The majority of branding is done via the NRO variables in settings.py. You might also want to change the logo of the application. Inside the static/img/eduroam_branding folder you will find the xcf (Gimp) logo files logo_holder, logo small. Edit with Gimp according to your needs and save as logo_holder.png and logo_small.png inside the static/img folder
\ No newline at end of file
.. _require-label:
Required Packages
====================================================================
DjNRO heavily depends on the following:
* Python (<3 & >=2.6)
* Django (>=1.2) - python-django
* python-django-extensions
* python-mysqldb (If you wish to use MySQL as the DB backend)
* mysql-client-5.1
* python-ipaddr
* python-django-south (For database migrations)
* python-django-tinymce (Flatpages editing made easier)
* python-memcache (Yeap! You need that for Google maps locations caching)
* python-django-registration (User activation made easy)
* apache2 (We suggest apache - use your preferred one)
* apache2-mod-rewrite
* apache2-mod-wsgi
* apache2-shibboleth : The server should be setup as a Shibboleth SP
* A mail server - Tested with exim
Django Social Auth
-----------------------------
User authentication via social media is carried out by the `python-django-social-auth <http://http://django-social-auth.readthedocs.org/en/latest/index.html>`_ python-django-social-auth package. If your distro includes it, then go via your distro installation.
In any case we have included python-django-social-auth as an application inside the eduroam Django project.
Django Social Auth: Requirements - Dependencies
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
* python-django-social-auth
* OpenId support depends on python-openid
* OAuth support depends on python-oauth2
\ No newline at end of file
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment