root / docs / source / install.rst @ e5cbe795
History | View | Annotate | Download (12.3 kB)
1 |
.. _install-label: |
---|---|
2 |
|
3 |
Installation/Configuration |
4 |
========================== |
5 |
.. contents:: |
6 |
|
7 |
.. attention:: |
8 |
Installation instructions assume a clean Debian Wheezy with Django 1.4 |
9 |
|
10 |
Assuming that you have installed all the required packages as described in :ref:`require-label` you can install the djnro platform application. |
11 |
|
12 |
Currently the source code is availiable at code.grnet.gr and can be cloned via git:: |
13 |
|
14 |
git clone https://code.grnet.gr/git/djnro |
15 |
|
16 |
As with the majority of Django projects, settings.py has to be properly configured and then comes the population of the database. After git clone, copy settings.py.dist to settings.py:: |
17 |
|
18 |
cd djnro |
19 |
cp djnro/settings.py.dist djnro/settings.py |
20 |
|
21 |
|
22 |
Project Settings (settings.py) |
23 |
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ |
24 |
Settings.py file should not be edited, the variables that need to be altered are in local_settings.py.dist. |
25 |
To set up Djnro one must copy local_settings.py.dist, to local_settings.py and alter the settings according to |
26 |
the configuration of the host. |
27 |
|
28 |
The following variables/settings need to be altered or set: |
29 |
|
30 |
Set Admin contacts:: |
31 |
|
32 |
ADMINS = ( |
33 |
('Admin', 'admin@example.com'), |
34 |
) |
35 |
|
36 |
Set the database connection params:: |
37 |
|
38 |
DATABASES = { |
39 |
... |
40 |
} |
41 |
|
42 |
For a production instance and once DEBUG is set to False set the ALLOWED_HOSTS:: |
43 |
|
44 |
ALLOWED_HOSTS = ['.example.com'] |
45 |
|
46 |
Set your timezone and Languages:: |
47 |
|
48 |
TIME_ZONE = 'Europe/Athens' |
49 |
|
50 |
LANGUAGES = ( |
51 |
('el', _('Greek')), |
52 |
('en', _('English')), |
53 |
) |
54 |
|
55 |
Set your static root and url:: |
56 |
|
57 |
STATIC_ROOT = '/path/to/static' |
58 |
STATIC_URL = 'http://www.example.com/static' |
59 |
|
60 |
Set the secret key:: |
61 |
|
62 |
SECRET_KEY = '<put something really random here, eg. %$#%@#$^2312351345#$%3452345@#$%@#$234#@$hhzdavfsdcFDGVFSDGhn>' |
63 |
|
64 |
Django social auth needs changes in the Authentication Backends depending on which social auth you want to enable:: |
65 |
|
66 |
AUTHENTICATION_BACKENDS = ( |
67 |
'djnro.djangobackends.shibauthBackend.shibauthBackend', |
68 |
... |
69 |
'django.contrib.auth.backends.ModelBackend', |
70 |
) |
71 |
|
72 |
Set your template dirs:: |
73 |
|
74 |
TEMPLATE_DIRS = ( |
75 |
"/example/templates", |
76 |
) |
77 |
|
78 |
As the application includes a "Nearest Eduroam" functionality, world eduroam points are harvested via the eduroam.org kml file:: |
79 |
|
80 |
EDUROAM_KML_URL = 'http://monitor.eduroam.org/kml/all.kml' |
81 |
|
82 |
|
83 |
Depending on your AAI policy set an appropriate authEntitlement:: |
84 |
|
85 |
SHIB_AUTH_ENTITLEMENT = 'urn:mace:example.com:pki:user' |
86 |
|
87 |
Mail server parameters:: |
88 |
|
89 |
SERVER_EMAIL = "Example domain eduroam Service <noreply@example.com>" |
90 |
EMAIL_SUBJECT_PREFIX = "[eduroam] " |
91 |
|
92 |
NRO contact mails:: |
93 |
|
94 |
NOTIFY_ADMIN_MAILS = ["mail1@example.com", "mail2@example.com"] |
95 |
|
96 |
Set your cache backend (if you want to use one). For production instances you can go with memcached. For development you can switch to the provided dummy instance:: |
97 |
|
98 |
|
99 |
CACHES = { |
100 |
'default': { |
101 |
'BACKEND': 'django.core.cache.backends.memcached.MemcachedCache', |
102 |
'LOCATION': '127.0.0.1:11211', |
103 |
} |
104 |
} |
105 |
|
106 |
Models Name_i18n and URL_i18n include a language choice field |
107 |
If languages are the same with LANGUAGES variable, simply do URL_NAME_LANGS = LANGUAGES else set your own:: |
108 |
|
109 |
URL_NAME_LANGS = ( |
110 |
('en', 'English' ), |
111 |
('el', 'Ελληνικά'), |
112 |
) |
113 |
|
114 |
NRO specific parameters. Affect html templates:: |
115 |
|
116 |
# Frontend country specific vars, eg. Greece |
117 |
NRO_COUNTRY_NAME = _('My Country') |
118 |
# Variable used by context_processor to display the "eduroam | <country_code>" in base.html |
119 |
NRO_COUNTRY_CODE = 'gr' |
120 |
# main domain url used in right top icon, eg. http://www.grnet.gr |
121 |
NRO_DOMAIN_MAIN_URL = "http://www.example.com" |
122 |
# provider info for footer |
123 |
NRO_PROV_BY_DICT = {"name": "EXAMPLE DEV TEAM", "url": "http://devteam.example.com"} |
124 |
#NRO social media contact (Use: // to preserve https) |
125 |
NRO_PROV_SOCIAL_MEDIA_CONTACT = [ |
126 |
{"url":"//soc.media.url", "icon":"icon.png", "name":"NAME1(eg. Facebook)"}, |
127 |
{"url":"//soc.media.url", "icon":"icon.png", "name":"NAME2(eg. Twitter)"}, |
128 |
] |
129 |
# map center (lat, lng) |
130 |
MAP_CENTER = (36.97, 23.71) |
131 |
#Helpdesk, used in base.html: |
132 |
NRO_DOMAIN_HELPDESK_DICT = {"name": _("Domain Helpdesk"), 'email':'helpdesk@example.com', 'phone': '12324567890', 'uri': 'helpdesk.example.com'} |
133 |
|
134 |
Set the Realm country for REALM model:: |
135 |
|
136 |
#Countries for Realm model: |
137 |
REALM_COUNTRIES = ( |
138 |
('country_2letters', 'Country' ), |
139 |
) |
140 |
|
141 |
Shibboleth attribute MAP according to your AAI policy:: |
142 |
|
143 |
#Shibboleth attribute map |
144 |
SHIB_USERNAME = ['HTTP_EPPN'] |
145 |
SHIB_MAIL = ['mail', 'HTTP_MAIL', 'HTTP_SHIB_INETORGPERSON_MAIL'] |
146 |
SHIB_FIRSTNAME = ['HTTP_SHIB_INETORGPERSON_GIVENNAME'] |
147 |
SHIB_LASTNAME = ['HTTP_SHIB_PERSON_SURNAME'] |
148 |
SHIB_ENTITLEMENT = ['HTTP_SHIB_EP_ENTITLEMENT'] |
149 |
|
150 |
Django Social Auth parameters:: |
151 |
|
152 |
TWITTER_CONSUMER_KEY = '' |
153 |
TWITTER_CONSUMER_SECRET = '' |
154 |
|
155 |
FACEBOOK_APP_ID = '' |
156 |
FACEBOOK_API_SECRET = '' |
157 |
|
158 |
LINKEDIN_CONSUMER_KEY = '' |
159 |
LINKEDIN_CONSUMER_SECRET = '' |
160 |
|
161 |
LINKEDIN_SCOPE = ['r_basicprofile', 'r_emailaddress'] |
162 |
LINKEDIN_EXTRA_FIELD_SELECTORS = ['email-address', 'headline', 'industry'] |
163 |
LINKEDIN_EXTRA_DATA = [('id', 'id'), |
164 |
('first-name', 'first_name'), |
165 |
('last-name', 'last_name'), |
166 |
('email-address', 'email_address'), |
167 |
('headline', 'headline'), |
168 |
('industry', 'industry')] |
169 |
|
170 |
YAHOO_CONSUMER_KEY = '' |
171 |
YAHOO_CONSUMER_SECRET = '' |
172 |
|
173 |
GOOGLE_SREG_EXTRA_DATA = [] |
174 |
|
175 |
SOCIAL_AUTH_FORCE_POST_DISCONNECT = True |
176 |
|
177 |
FACEBOOK_EXTENDED_PERMISSIONS = ['email'] |
178 |
|
179 |
SOCIAL_AUTH_LOGIN_REDIRECT_URL = '/manage/' |
180 |
LOGIN_REDIRECT_URL = '/manage/' |
181 |
SOCIAL_AUTH_INACTIVE_USER_URL = '/manage/' |
182 |
|
183 |
SOCIAL_AUTH_FORCE_POST_DISCONNECT = True |
184 |
SOCIAL_AUTH_REDIRECT_IS_HTTPS = True |
185 |
SOCIAL_AUTH_CREATE_USERS = True |
186 |
SOCIAL_AUTH_FORCE_RANDOM_USERNAME = False |
187 |
SOCIAL_AUTH_SANITIZE_REDIRECTS = False |
188 |
|
189 |
|
190 |
|
191 |
SOCIAL_AUTH_PIPELINE = ( |
192 |
'social_auth.backends.pipeline.social.social_auth_user', |
193 |
'social_auth.backends.pipeline.user.get_username', |
194 |
'social_auth.backends.pipeline.user.create_user', |
195 |
'social_auth.backends.pipeline.social.associate_user', |
196 |
'social_auth.backends.pipeline.social.load_extra_data', |
197 |
'social_auth.backends.pipeline.user.update_user_details', |
198 |
) |
199 |
|
200 |
.. versionadded:: 0.9 |
201 |
|
202 |
Support for eduroam CAT can be set via the corresponding variables/dicts. Make sure to **always** include a 'production' instance record for CAT_INSTANCES and CAT_AUTH. |
203 |
What you really need to make CAT work is a CAT_API_KEY and the CAT_API_URL. The CAT_PROFILES_URL is the base url of the landing page where your institution users can download device profile configurations:: |
204 |
|
205 |
CAT_INSTANCES = ( |
206 |
('production', 'Production Instance'), |
207 |
('testing', 'Testing Instance'), |
208 |
('dev1', 'Dev1 Instance'), |
209 |
) |
210 |
|
211 |
CAT_AUTH = { |
212 |
'production':{"CAT_API_KEY":"<provided API key>", |
213 |
"CAT_API_URL":"https://cat-test.eduroam.org/test/admin/API.php", |
214 |
"CAT_PROFILES_URL":"https://cat-test.eduroam.org/test/admin/API.php", |
215 |
"CAT_FEDMGMT_URL":"https://cat.eduroam.org/admin/overview_federation.php"}, |
216 |
'testing':{"CAT_API_KEY":"<provided API key>", |
217 |
"CAT_API_URL":"https://cat-test.eduroam.org/test/admin/API.php", |
218 |
"CAT_PROFILES_URL":"https://cat-test.eduroam.org/test/admin/API.php", |
219 |
"CAT_FEDMGMT_URL":"https://cat.eduroam.org/admin/overview_federation.php"}, |
220 |
'dev1':{"CAT_API_KEY":"<provided API key>", |
221 |
"CAT_API_URL":"https://cat-test.eduroam.org/test/admin/API.php", |
222 |
"CAT_PROFILES_URL":"https://cat-test.eduroam.org/test/admin/API.php", |
223 |
"CAT_FEDMGMT_URL":"https://cat.eduroam.org/admin/overview_federation.php"}, |
224 |
} |
225 |
|
226 |
For more administrative info on eduroam CAT, you can visit: `A guide to eduroam CAT for federation administrators <https://confluence.terena.org/display/H2eduroam/A+guide+to+eduroam+CAT+for+federation+administrators>`_. |
227 |
|
228 |
Database Sync |
229 |
^^^^^^^^^^^^^ |
230 |
|
231 |
Once you are done with settings.py run:: |
232 |
|
233 |
./manage.py syncdb |
234 |
|
235 |
Create a superuser, it comes in handy. And then run south migration to complete:: |
236 |
|
237 |
./manage.py migrate |
238 |
|
239 |
Now you should have a clean database with all the tables created. |
240 |
|
241 |
Running the server |
242 |
^^^^^^^^^^^^^^^^^^ |
243 |
|
244 |
We suggest going via Apache with mod_wsgi. Below is an example configuration:: |
245 |
|
246 |
WSGIDaemonProcess djnro processes=3 threads=20 display-name=%{GROUP} python-path=/path/to/djnro/ |
247 |
WSGIProcessGroup djnro |
248 |
|
249 |
... |
250 |
|
251 |
<VirtualHost *:443> |
252 |
ServerName example.com |
253 |
ServerAdmin admin@example.com |
254 |
ServerSignature On |
255 |
|
256 |
<Files wsgi.py> |
257 |
Order deny,allow |
258 |
Allow from all |
259 |
</Files> |
260 |
|
261 |
|
262 |
SSLEngine on |
263 |
SSLCertificateFile ... |
264 |
SSLCertificateChainFile ... |
265 |
SSLCertificateKeyFile ... |
266 |
|
267 |
# Shibboleth SP configuration |
268 |
ShibConfig /etc/shibboleth/shibboleth2.xml |
269 |
Alias /shibboleth-sp /usr/share/shibboleth |
270 |
|
271 |
# Integration of Shibboleth into Django app: |
272 |
|
273 |
<Location /login> |
274 |
AuthType shibboleth |
275 |
ShibRequireSession On |
276 |
ShibUseHeaders On |
277 |
require valid-user |
278 |
</Location> |
279 |
|
280 |
|
281 |
<Location /Shibboleth.sso> |
282 |
SetHandler shib |
283 |
</Location> |
284 |
|
285 |
|
286 |
Alias /static /path/to/djnro/static |
287 |
WSGIScriptAlias / /path/to/djnro/djnro/wsgi.py |
288 |
ErrorLog /var/log/apache2/error.log |
289 |
CustomLog /var/log/apache2/access.log combined |
290 |
</VirtualHost> |
291 |
|
292 |
*Info*: It is strongly suggested to allow access to /admin|overview|alt-login *ONLY* from trusted subnets. |
293 |
|
294 |
Once you are done, restart apache. |
295 |
|
296 |
Initial Data |
297 |
^^^^^^^^^^^^ |
298 |
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). |
299 |
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 |
300 |
|
301 |
Next Steps (Set your Logo) |
302 |
^^^^^^^^^^^^^^^^^^^^^^^^^^ |
303 |
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. To change the domain logo on top right, replace the static/img/right_logo_small.png file with your own logo (86x40). |
304 |
|
305 |
Upgrade Instructions |
306 |
^^^^^^^^^^^^^^^^^^^^ |
307 |
* Backup your settings.py file. |
308 |
|
309 |
* Copy loca_settings.py.dist to local_settings.py and fill the configuration according to the settings.py from your v0.8 instance. |
310 |
|
311 |
* edit the apache configuration in order to work with the new location of wsgi and |
312 |
set the python-path attribute. |
313 |
|
314 |
* remove old wsgi file '/path/to/djnro/apache/django.wsgi' |
315 |
|
316 |
* remove old settings.py.dist |
317 |
|
318 |
* remove django-extensions from `INSTALLED_APPS` |
319 |
|
320 |
* Add timeout in cache configuration |
321 |
|
322 |
* Required packages: |
323 |
|
324 |
* python-oauth2 |
325 |
|
326 |
* python-requests |
327 |
|
328 |
* python-lxml |
329 |
|
330 |
* python-yaml |
331 |
|
332 |
* run manage.py migrate |
333 |
|
334 |
|
335 |
Pip Support |
336 |
^^^^^^^^^^^^ |
337 |
We have added a requirements.txt file, tested for django 1.4.5. You can use it |
338 |
with `pip install -r requirements.txt`. |
339 |
|
340 |
|
341 |
Ldap Authentication |
342 |
^^^^^^^^^^^^^^^^^^^ |
343 |
In case you want to use Ldap authentication:: |
344 |
|
345 |
AUTHENTICATION_BACKENDS = ( |
346 |
..., |
347 |
'django_auth_ldap.backend.LDAPBackend', |
348 |
..., |
349 |
) |
350 |
|
351 |
# LDAP CONFIG |
352 |
import ldap |
353 |
from django_auth_ldap.config import LDAPSearch, GroupOfNamesType |
354 |
AUTH_LDAP_BIND_DN = "" |
355 |
AUTH_LDAP_BIND_PASSWORD = "" |
356 |
AUTH_LDAP_SERVER_URI = "ldap://foo.bar.org" |
357 |
AUTH_LDAP_START_TLS = True |
358 |
AUTH_LDAP_USER_SEARCH = LDAPSearch("ou=People, dc=bar, dc=foo", |
359 |
ldap.SCOPE_SUBTREE, "(uid=%(user)s)") |
360 |
AUTH_LDAP_USER_ATTR_MAP = { |
361 |
"first_name":"givenName", |
362 |
"last_name": "sn", |
363 |
"email": "mail |
364 |
} |
365 |
# Set up the basic group parameters. |
366 |
AUTH_LDAP_GROUP_SEARCH = LDAPSearch( |
367 |
"ou=Groups,dc=foo,dc=bar,dc=org",ldap.SCOPE_SUBTREE, objectClass=groupOfNames" |
368 |
) |
369 |
AUTH_LDAP_GROUP_TYPE = GroupOfNamesType() |
370 |
AUTH_LDAP_USER_FLAGS_BY_GROUP = { |
371 |
"is_active": "cn=NOC, ou=Groups, dc=foo, dc=bar, dc=org", |
372 |
"is_staff": "cn=staff, ou=Groups, dc=foo, dc=bar, dc=org", |
373 |
"is_superuser": "cn=NOC, ou=Groups,dc=foo, dc=bar, dc=org" |
374 |
} |