install.md 14.3 KB
Newer Older
1 2 3
# Installation/Configuration
First of all you have to install all the packages described in `requirements`
section
4

5
The software is published at [github](https://github.com/grnet/djnro) and can be downloaded using git:
6

7
	git clone https://github.com/grnet/djnro
8

9

10
## Project & Local Settings
11

12
**In version 0.9 settings were split in two parts: settings.py and local_settings.py**
13

14 15
The file settings.py contains settings distributed by the project, which should normally not be necessary to modify.
Options specific to the particular installation must be configured in local_settings.py. This file must be created by copying local_settings.py.dist:
16

17
    cd djnro
18
    cp djnro/local_settings.py.dist djnro/local_settings.py
19

20

21
The following variables/settings need to be altered or set:
Stauros Kroustouris's avatar
Stauros Kroustouris committed
22

23 24 25 26 27 28
Set Admin contacts::

	ADMINS = (
	     ('Admin', 'admin@example.com'),
	)

29
Set the database connection params:
30 31 32 33 34

	DATABASES = {
	    ...
	}

35
For a production instance and once DEBUG is set to False set the ALLOWED_HOSTS:
36 37 38

    ALLOWED_HOSTS = ['.example.com']
    SECRET_KEY = '<put something really random here, eg. %$#%@#$^2312351345#$%3452345@#$%@#$234#@$hhzdavfsdcFDGVFSDGhn>'
39

40
Django social auth needs changes in the Extra Authentication Backends depending on which social auth you want to enable:
Stauros Kroustouris's avatar
Stauros Kroustouris committed
41

42
	EXTRA_AUTHENTICATION_BACKENDS = (
Stauros Kroustouris's avatar
Stauros Kroustouris committed
43
	    'djnro.djangobackends.shibauthBackend.shibauthBackend',
44 45 46 47
		...
		'django.contrib.auth.backends.ModelBackend',
	)

48
**The default Authentication Backends are in settings.py**
49

50
As the application includes a "Nearest eduroam" functionality, global eduroam service locations are harvested from the KML file published at eduroam.org::
Stauros Kroustouris's avatar
Stauros Kroustouris committed
51

52 53
	EDUROAM_KML_URL = 'http://monitor.eduroam.org/kml/all.kml'

Stauros Kroustouris's avatar
Stauros Kroustouris committed
54

55
Depending on your AAI policy set an appropriate authEntitlement::
56

57 58 59 60 61 62 63 64 65 66 67
	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"]

68
Set your cache backend (if you want to use one). For production instances you can go with memcached. For development you can keep the provided dummy instance::
69

70

71 72 73 74 75 76
    CACHES = {
        'default': {
            'BACKEND': 'django.core.cache.backends.memcached.MemcachedCache',
            'LOCATION': '127.0.0.1:11211',
        }
    }
77

78
NRO specific parameters. These affect HTML templates::
79 80 81

	# Frontend country specific vars, eg. Greece
	NRO_COUNTRY_NAME = _('My Country')
Stauros Kroustouris's avatar
Stauros Kroustouris committed
82
	# Variable used by context_processor to display the "eduroam | <country_code>" in base.html
83 84 85
	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"
86 87
	# provider info for footer
	NRO_PROV_BY_DICT = {"name": "EXAMPLE DEV TEAM", "url": "http://devteam.example.com"}
88
	#NRO social media contact (Use: // to preserve https)
89
	NRO_PROV_SOCIAL_MEDIA_CONTACT = [
Stauros Kroustouris's avatar
Stauros Kroustouris committed
90
	                                {"url":"//soc.media.url", "icon":"icon.png", "name":"NAME1(eg. Facebook)"},
91 92 93 94
	                                {"url":"//soc.media.url", "icon":"icon.png",  "name":"NAME2(eg. Twitter)"},
	                                ]
	# map center (lat, lng)
	MAP_CENTER = (36.97, 23.71)
Stauros Kroustouris's avatar
Stauros Kroustouris committed
95
	#Helpdesk, used in base.html:
96 97
	NRO_DOMAIN_HELPDESK_DICT = {"name": _("Domain Helpdesk"), 'email':'helpdesk@example.com', 'phone': '12324567890', 'uri': 'helpdesk.example.com'}

98

Stauros Kroustouris's avatar
Stauros Kroustouris committed
99
Set the Realm country for REALM model::
100 101 102 103 104 105

	#Countries for Realm model:
	REALM_COUNTRIES = (
	             ('country_2letters', 'Country' ),
	            )

106
### Custom content in footer
107

108
If you need to present custom content in the footer at the bottom of the every page, you can add HTML/template code in `djnro/templates/partial/extra.footer.html`.
109 110


111
Attribute map to match your AAI policy and SSO software (typically Shibboleth SP)::
112 113 114 115 116 117 118 119

	#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']

120
Django Social Auth parameters:
121

Kroustouris Stavros's avatar
Kroustouris Stavros committed
122 123 124 125 126
	SOCIAL_AUTH_TWITTER_KEY = ''
	SOCIAL_AUTH_TWITTER_SECRET = ''
	SOCIAL_AUTH_GOOGLE_OAUTH2_KEY = ''
	SOCIAL_AUTH_GOOGLE_OAUTH2_SECRET = ' '
	SOCIAL_AUTH_GOOGLE_OAUTH2_SCOPE = []
127

128

129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144
DjNRO provides limited integration with eduroam CAT (Configuration Assistant Tool). Institution administrators can automatically provision their institution to CAT without the intervention of the federation (NRO) administrator.

In order to enable this functionality, you must list at least one instance and the corresponding description in CAT_INSTANCES. Beware that pages accessible by end users currently only show CAT information
for the instance named `production`.

You must also set the following parameters for each CAT instance in CAT_AUTH:

* CAT_API_KEY: API key for authentication to CAT

* CAT_API_URL: API endpoint URL

* CAT_PROFILES_URL: Base URL for Intitution Download Area pages

* CAT_FEDMGMT_URL: URL For Federation Overview page (currently not in use)

::
145 146

    CAT_INSTANCES = (
147 148 149
        ('production', 'cat.eduroam.org'),
        ('testing', 'cat-test.eduroam.org'),
    )
150

151
    CAT_AUTH = {
152 153 154 155 156 157 158 159 160 161 162 163 164 165
        'production': {
            "CAT_API_KEY": "<provided API key>",
            "CAT_API_URL": "https://cat.eduroam.org/admin/API.php",
            "CAT_PROFILES_URL": "https://cat.eduroam.org/",
            "CAT_FEDMGMT_URL": "https://cat.eduroam.org/admin/overview_federation.php"
        },
        'testing': {
            "CAT_API_KEY": "<provided API key>",
            "CAT_API_URL": "https://cat-test.eduroam.org/test/admin/API.php",
            "CAT_PROFILES_URL": "https://cat-test.eduroam.org/test",
            "CAT_FEDMGMT_URL": "https://cat-test.eduroam.org/test/admin/overview_federation.php"
        },
    }

166
For more information about eduroam CAT, you may read: [A guide to eduroam CAT for federation administrators](https://confluence.terena.org/display/H2eduroam/A+guide+to+eduroam+CAT+for+federation+administrators).
167

168 169
### Extra Apps
In case one wants to extend some of the settings only for the local instance, they can prepend *EXTRA_* on the attribute they want to extend. For example:
170

171 172 173 174
	EXTRA_INSTALLED_APPS = (
		'django_debug_toolbar',
	)

175 176
## Database Sync
Once you are done with local_settings.py run:
177 178 179 180 181 182 183 184 185

	./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.

186 187
## Running the server

188

Zenon Mousmoulas's avatar
Zenon Mousmoulas committed
189
We suggest using Apache and mod_wsgi. Below is an example configuration::
190

191 192
	# Tune wsgi daemon as necessary: processes=x threads=y
	WSGIDaemonProcess djnro display-name=%{GROUP} python-path=/path/to/djnro/
Stauros Kroustouris's avatar
Stauros Kroustouris committed
193

194 195
	<VirtualHost *:443>
		ServerName		example.com
Kroustouris Stauros's avatar
Kroustouris Stauros committed
196

197 198 199 200 201 202 203 204 205
		Alias		/static	/path/to/djnro/static
		WSGIScriptAlias	/	/path/to/djnro/djnro/wsgi.py
		<Directory /path/to/djnro/djnro>
			<Files wsgi.py>
			    WSGIProcessGroup djnro
			    Order deny,allow
			    Allow from all
			</Files>
		</Directory>
Kroustouris Stauros's avatar
Kroustouris Stauros committed
206

207 208
		SSLEngine on
		SSLCertificateFile	...
209
		SSLCertificateChainFile	...
210
		SSLCertificateKeyFile	...
Stauros Kroustouris's avatar
Stauros Kroustouris committed
211

212
		# Shibboleth SP configuration
213 214
		ShibConfig	/etc/shibboleth/shibboleth2.xml
		Alias		/shibboleth-sp	/usr/share/shibboleth
Stauros Kroustouris's avatar
Stauros Kroustouris committed
215

216
		# SSO through Shibboleth SP:
217 218 219 220 221 222 223 224 225 226 227
		<Location /login>
			AuthType shibboleth
			ShibRequireSession On
			ShibUseHeaders On
			require valid-user
		</Location>
		<Location /Shibboleth.sso>
			SetHandler shib
		</Location>
	</VirtualHost>

Vladimir Mencl's avatar
Vladimir Mencl committed
228 229 230 231 232 233 234 235 236 237 238
Alternatively, it is possible to use Apache with mod_proxy_http to pass the requests to uwsgi.  In that case, the ````WSGIScriptAlias```` directive would be replaced with the following:

                ProxyRequests off
                ProxyPreserveHost on

                ProxyPass / http://localhost:3031/
                ProxyPassReverse / http://localhost:3031/

                # tell DjNRO we have forwarded over SSL
                RequestHeader set X-Forwarded-Protocol https

239
*Info*: It is strongly recommended to allow access to `/(admin|overview|alt-login)` *ONLY* from trusted subnets.
Stauros Kroustouris's avatar
Stauros Kroustouris committed
240

241 242
Once you are done, restart apache.

243
## Fetch KML
244
A Django management command, named fetch_kml, fetches the KML document and updates the cache with eduroam service locations. It is suggested to periodically run this command in a cron job in order to keep the map up to date::
245 246 247

		./manage.py fetch_kml

248
## Initial Data
249

250 251
In order to start using DjNRO you need to create a Realm record for your NRO along with one or more contacts linked to it. You can visit the Django admin interface `https://<hostname>/admin` and add a Realm (remember to set REALM_COUNTRIES in local_settings.py).
In DjNRO the NRO sets the environment for the institution eduroam admins. Therefore the NRO has to insert the initial data for his/her clients/institutions in the *Institutions* Model, again using the Django admin interface. As an alternative, you can copy your existing `institution.xml` to `/path/to/djnro` and run the following to import institution data::
252

253
		./manage.py parse_instituion_xml
254

255
## Exporting Data
256 257
DjNRO can export data in formats suitable for use by other software.

Kroustouris Stauros's avatar
Kroustouris Stauros committed
258
XML documents conforming to the [eduroam database](https://monitor.eduroam.org/database.php>) schemata are exported at the following URLs, as required for harvesting by eduroam.org:
259 260 261 262 263

    /general/realm.xml
    /general/institution.xml
    /usage/realm_data.xml

Kroustouris Stauros's avatar
Kroustouris Stauros committed
264
A list of institution administrators can be exported in CSV format or a plain format suitable for use by a mailing list (namely [Sympa](http://www.sympa.org/manual/parameters-data-sources#include_remote_file>). This data is available through:
265

266
* a management comand `./manage.py contacts`, which defaults to CSV output (currently with headers in Greek!) and can switch to plain output using `--mail-list`.
267

268
* a view (`adminlist`), which only supports output in the latter plain text format.
269 270 271

Likewise, data that can be used as input for automatic configuration of `Federation Level RADIUS Servers (FLRS)` can be exported in YAML/JSON format, through:

272
* a management command (`./manage.py servdata`)
273

274
* a view (`sevdata`)
275 276 277

Output format defaults to YAML and can be overriden respectively:

278
* by using `--output=json`
279

280
* by sending an `Accept: application/json` HTTP header
281

282
We also provide a sample script for reading this data (`extras/servdata_consumer.py`) along with templates (in the same directory) for producing configuration suitable for FreeRADIUS and radsecproxy. This script requires the following python packages:
283 284 285 286 287 288 289

  * python-requests

  * python-yaml

  * python-mako (for the templates)

290 291 292 293
Take the time to read the default settings at the top of the script and run it with `--help`. The templates are based on assumptions that may not match your setup; they are mostly provided as a proof of concept.

*attention*
   **The `adminlist` and `servdata` views are commented out by default in `djnro/urls.py`. Make sure you protect them (SSL, ACL and/or authentication) at the HTTP server before you enable them, as they may expose private/sensitive data.**
294

295
## Next Steps (Branding)
296

297
The majority of branding is done via the NRO variables in local_settings.py. You might also want to change the logo of the application. Within the static/img/eduroam_branding folder you will find the XCF files logo_holder, logo_small.
298

299 300 301
## Upgrade Instructions

* Backup your `settings.py` and `local_settings` file and any local modifications.
302 303

* Update the code.
Kroustouris Stauros's avatar
Kroustouris Stauros committed
304

305
* Copy `djnro/local_settings.py.dist` to `djnro/local_settings.py` and modify it to match your previous configuration.
306

307
* edit the apache configuration in order to work with the new location of wsgi and set the python-path attribute.
Kroustouris Stauros's avatar
Kroustouris Stauros committed
308

309
* remove old wsgi file `/path/to/djnro/apache/django.wsgi` and parent directory
Kroustouris Stauros's avatar
Kroustouris Stauros committed
310

Kroustouris Stauros's avatar
Kroustouris Stauros committed
311 312 313 314
* remove django-extensions from `INSTALLED_APPS`

* Add timeout in cache configuration

315
* Make sure you have installed the following required packages (some of these introduced in 0.9):
Kroustouris Stauros's avatar
Kroustouris Stauros committed
316

Zenon Mousmoulas's avatar
Zenon Mousmoulas committed
317
  * python-oauth2
Kroustouris Stauros's avatar
Kroustouris Stauros committed
318

Zenon Mousmoulas's avatar
Zenon Mousmoulas committed
319
  * python-requests
Kroustouris Stauros's avatar
Kroustouris Stauros committed
320

Zenon Mousmoulas's avatar
Zenon Mousmoulas committed
321
  * python-lxml
Kroustouris Stauros's avatar
Kroustouris Stauros committed
322

Zenon Mousmoulas's avatar
Zenon Mousmoulas committed
323
  * python-yaml
Kroustouris Stauros's avatar
Kroustouris Stauros committed
324

325
* run `./manage.py migrate`
Kroustouris Stauros's avatar
Kroustouris Stauros committed
326

327
*attention*
328

329
   **You had previously copied `urls.py.dist` to `urls.py`. This is no longer supported; we now use `djnro/urls.py`. URLs that provide sensitive data are disabled (commented out) by default. You may have to edit the file according to your needs.**
Kroustouris Stauros's avatar
Kroustouris Stauros committed
330

331
## LDAP Authentication
Kroustouris Stauros's avatar
Kroustouris Stauros committed
332

333
If you want to use LDAP authentication, local_settings.py must be amended::
Kroustouris Stavros's avatar
Kroustouris Stavros committed
334

335
	EXTRA_AUTHENTICATION_BACKENDS = (
Kroustouris Stauros's avatar
Kroustouris Stauros committed
336 337 338 339 340 341
		...,
		'django_auth_ldap.backend.LDAPBackend',
		...,
	)

	# LDAP CONFIG
Kroustouris Stauros's avatar
Kroustouris Stauros committed
342
	import ldap
Kroustouris Stavros's avatar
Kroustouris Stavros committed
343
	from django_auth_ldap.config import LDAPSearch, GroupOfNamesType
Kroustouris Stauros's avatar
Kroustouris Stauros committed
344 345 346 347 348 349 350 351 352 353 354 355 356 357 358 359 360 361 362 363 364
	AUTH_LDAP_BIND_DN = ""
	AUTH_LDAP_BIND_PASSWORD = ""
	AUTH_LDAP_SERVER_URI = "ldap://foo.bar.org"
	AUTH_LDAP_START_TLS = True
	AUTH_LDAP_USER_SEARCH = LDAPSearch("ou=People, dc=bar, dc=foo",
	ldap.SCOPE_SUBTREE, "(uid=%(user)s)")
	AUTH_LDAP_USER_ATTR_MAP = {
	      "first_name":"givenName",
	      "last_name": "sn",
	      "email": "mail
	      }
	# Set up the basic group parameters.
	AUTH_LDAP_GROUP_SEARCH = LDAPSearch(
		"ou=Groups,dc=foo,dc=bar,dc=org",ldap.SCOPE_SUBTREE, objectClass=groupOfNames"
	)
	AUTH_LDAP_GROUP_TYPE = GroupOfNamesType()
	AUTH_LDAP_USER_FLAGS_BY_GROUP = {
		"is_active": "cn=NOC, ou=Groups, dc=foo, dc=bar, dc=org",
		"is_staff": "cn=staff, ou=Groups, dc=foo, dc=bar, dc=org",
		"is_superuser": "cn=NOC, ou=Groups,dc=foo, dc=bar, dc=org"
	}
365

366

367 368
## Pebble Watch Application - pebduroam

369 370 371 372 373

The closest point API allows for development of location aware-applications.
Pebduroam is a Pebble watch application that fetches the closest eduroam access point plus walking instructions on how to reach it.
Installing the application on your Pebble watch can be done in 2 ways:

Kroustouris Stauros's avatar
Kroustouris Stauros committed
374
* You can install the application via the Pebble App Store: [pebduroam](https://apps.getpebble.com/applications/5384b2119c84af48350000c7>)
375

Kroustouris Stauros's avatar
Kroustouris Stauros committed
376
* You can install the application and contribute to its development via github: [pebduroam github repo](https://github.com/leopoul/pebduroam>).
377 378

  * You need to have a Cloudpebble account to accomplish this.
379

380
  * Once logged-in you need to select Import - Import from github and paste the pebduroam github repo url in the corresponding text box.
381

382 383
  * Having configured your Pebble watch in developer mode will allow you to build and install your cloned project source directly on your watch.

384 385
**attention**
   Currently pebduroam uses GRNET's djnro closest point API. To switch the Pebble app to your djnro installation you need to follow the second method of installation
386