README.rst 16 KB
Newer Older
André Anjos's avatar
André Anjos committed
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
.. vim: set fileencoding=utf-8 :

.. Copyright (c) 2016 Idiap Research Institute, http://www.idiap.ch/          ..
.. Contact: beat.support@idiap.ch                                             ..
..                                                                            ..
.. This file is part of the beat.web module of the BEAT platform.             ..
..                                                                            ..
.. Commercial License Usage                                                   ..
.. Licensees holding valid commercial BEAT licenses may use this file in      ..
.. accordance with the terms contained in a written agreement between you     ..
.. and Idiap. For further information contact tto@idiap.ch                    ..
..                                                                            ..
.. Alternatively, this file may be used under the terms of the GNU Affero     ..
.. Public License version 3 as published by the Free Software and appearing   ..
.. in the file LICENSE.AGPL included in the packaging of this file.           ..
.. The BEAT platform is distributed in the hope that it will be useful, but   ..
.. WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY ..
.. or FITNESS FOR A PARTICULAR PURPOSE.                                       ..
..                                                                            ..
.. You should have received a copy of the GNU Affero Public License along     ..
.. with the BEAT platform. If not, see http://www.gnu.org/licenses/.          ..


============================================
 Biometrics Evaluation and Testing Platform
============================================

This package contains the source code for the web components of the BEAT
platform.


Installation
------------

Here is a recipe to get you started::

  $ python bootstrap-buildout.py
  $ ./bin/buildout

These 2 commands should download and install all non-installed dependencies and
get you a fully operational test and development environment.

.. note::

  The python shell used in the first line of the previous command set
  determines the python interpreter that will be used for all scripts developed
  inside this package.

  If you are on the Idiap filesystem, you may use
  ``/idiap/project/beat/environments/staging/usr/bin/python`` to bootstrap this
  package instead. It contains the same setup deployed at the final BEAT
  machinery.


.. tip::

  If you'd like to **speed-up** the installation, it is strongly advised you
  prepare a preset virtual environment (see the virtualenv_ package) with all
  required dependencies, so that ``./bin/buildout`` does not download and
  installs all of them every time you cleanup. This technique should allow you
  to quickly clean-up and re-start your working environment which is useful
  during development.

  In order to fetch currently needed dependencies, run::

    $ ./bin/buildout #to setup once
    $ ./bin/pip freeze > requirements.txt

  Examine the file ``requirements.txt`` and remove packages you are either
  developing locally (e.g., all that are under ``src``) or that you think you
  don't need. The command ``pip freeze`` reports all installed packages and not
  only those which are needed by your project. If the Python prompt you used
  for bootstrapping already had a good set of packages installed, you may see
  them there.

  Once you have a satisfying ``requirements.txt`` file, you may proceed to
  recreate a virtualenv_ you'll use for your development. Just call::

    $ virtualenv ~/work/beat-env #--system-site-packages

  To create the virtual environment. This new environment does not contain
  system packages by default. You may override that by specifying
  ``--system-site-packages`` as suggested above. Then, install the required
  packages on your new virtual environment::

    $ ~/work/beat-env/bin/pip install -r requirements.txt

  After that step is done, your virtual environment is ready for deployment.
  You may now start from scratch to develop ``beat.web`` taking as base the
  Python interpreter on your virtualenv_::

    $ cd beat.web
    $ git clean -fdx #full clean-up
    $ ~/work/beat-env/bin/python bootstrap-buildout.py
    $ ./bin/buildout

  You'll realize the buildout step now takes considerably less time and you may
  repeat this last step as much as needed. ``pip`` is a very flexible tool and
  you may use it to manage the virtualenv_ installing and removing packages as
  needed.


Documentation
-------------

Our documentation project is divided in 3 parts. The user guide is the only one
which is automatically built as part of the ``buildout`` procedure. The API and
108
administrators guide need to be manually compiled if required.
André Anjos's avatar
André Anjos committed
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144

To build the API documentation, just do::

  $ ./bin/sphinx-apidoc --separate -d 2 --output=doc/api/api beat beat/web/*/migrations beat/web/*/tests
  $ ./bin/sphinx-build doc/api html/api


To build the administrator guide, just do::

  $ ./bin/sphinx-build doc/admin html/admin


The above commands will build the stated guides, in HTML format, and dump
results into your local directory ``html``. You may navigate then to that
directory and, with your preferred web browser, open the file ``index.html`` to
browse the available documentation.

The basic user guide which includes information for users of the platform, is
built automatically upon ``buildout``. If you wish to build it and place it
alongside the other guides, you may do it as well like this::

  $ ./bin/sphinx-build doc/user html/user


Instantiating a BEAT web server
-------------------------------

For a simple (development) web server, the default settings on
``beat/web/settings/settings.py`` should work out of the box. These settings:

  * Instantiate the web service on the local host under port 8000 (the address
    will be ``http://127.0.0.1:8000``
  * Use an SQLITE3 database named ``django.sql3`` located on the current
    working directory
  * Run with full debug output
  * It sets the working BEAT prefix to ``./prefix``
145
146
  * A single user, called ``user`` (password ``user``) will be setup into the
    system
André Anjos's avatar
André Anjos committed
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188

If you need to tweak these settings, just edit the file
``beat/web/settings/settings.py``. You may consult the `Django documentation`_
for detailed information on other settings.

Once the Django settings are in place, you can run a single command to fully
populate a development webserver::

  $ ./bin/django install -v1

.. note::

   Concerning databases installed by this command, we only explain the platform
   how to **access** their data. It does not download the raw data for the
   databases that you must procure yourself through the relevant web sites
   (checkout the database pages on the Idiap instance of the BEAT platform for
   details).

.. note::

  If you need to specify your own path to the directories containing the
  databases, you could just create a simple JSON file as follows::

    {
      "atnt/1": "/remote/databases/atnt",
      "banca/2": "/remote/databases/banca"
    }

  Then just use the previous script with the option ``--database-root-file``::

    $ ./bin/django install -v1 --database-root-file=MYFILE.json

  By default, paths to the root of all databases are set to match the Idiap
  Research Institute filesystem organisation.

.. note::

  For every installed database, you'll need to generate their data indices,
  which allows the platform to correctly parallelize algorithms. To do so, for
  every combination of database and version you wish to support, run the
  following command::

189
    $ ./bin/beat -p prefix db index <name>/<version>
André Anjos's avatar
André Anjos committed
190
191
192
193
194

  Replacing the strings ``<name>`` by the name of the database you wish to dump
  the indices for, together with the version in ``<version>``. For example, to
  dump the indices for the AT&T database, version 1, do the following::

195
    $ ./bin/beat -p prefix db index atnt/1
André Anjos's avatar
André Anjos committed
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243

Once the contributions and users are in place, you're ready to start the test
server::

  $ ./bin/django runserver -v3

At this point, your platform can be accessed by typing the URL
``http://127.0.0.1:8000`` in a web browser on the machine the server is
running.

.. _localhost:

Localhost
---------

To effectively use your new server and test all aspects of it, you'll also need
a scheduler with at least one attached worker that can execute experiments. For
most development purposes, a simple 3-node system, with all components running
on the current (local) host is sufficient.

Here is a recipe to start a simple 3-node system in which the local worker uses
the system-wide installed Python interpreter to execute the algorithms.

First, make sure the program ``cpulimit`` is available on your system. The BEAT
platform uses this program to control slot usage on the scheduling/worker
level::

  $ cpulimit -h

If that is not the case, then you need to install it. Either install a package
that is native to your system (e.g. on Debian or Ubuntu platforms) or compile
the checked-out version available at ``src/cpulimit``::

  $ cd src/cpulimit;
  $ make
  $ ./src/cpulimit -h #to test it
  $ cd ../../bin #go back to the root of beat.web and the into the `bin' dir
  $ ln -s ../src/cpulimit/src/cpulimit
  $ cd .. #go back to the root of beat.web

Now start the localhost system::

  $ ./bin/localhost.py -v
  ...

You may inspect this programs help message for details on its usage and
options.

244
245
246
Once the localhost system is started you may open a browser window to your
`localhost, port 8000 <http://127.0.0.1:8000>`_, to get started with your
locally installed platform.
André Anjos's avatar
André Anjos committed
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264


Localhost with ``DEBUG=False``
==============================

If you need to test the RESTful API, it is better to do it without Django
throwing you HTML error pages. For that, you'll need to start the Django
development server with slightly different settings::

  $ ./bin/localhost.py -v --settings=beat.web.settings.nodebug


Unit Testing
------------

After installation, it is possible to run our suite of unit tests. To do so,
use::

265
  $ ./bin/django test --settings=beat.web.settings.test -v 1
André Anjos's avatar
André Anjos committed
266
267
268
269
270

You may pass filtering criteria to just launch tests for a particular set of
``beat.web`` applications. For example, to run tests only concerning
``beat.web.toolchains``, run::

271
  $ ./bin/django test --settings=beat.web.settings.test -v 1 beat.web.toolchains.tests
André Anjos's avatar
André Anjos committed
272
273
274

To measure coverage, you must set an environment variable for nose::

275
276
  $ ./bin/coverage run --source='./beat/web' ./bin/django test --settings=beat.web.settings.test
  $ ./bin/coverage report
André Anjos's avatar
André Anjos committed
277

278
279
280
281
Or, to generate an HTML report::

  $ ./bin/coverate html

282
283
284
285
286
287
.. tip::

   You may significatively speed-up your testing by re-using the same test
   database from run to run. In order to do this, just specify the flag
   ``--keepdb`` when you run your tests::

288
     $ ./bin/django test --settings=beat.web.settings.test -v 1 --keepdb
289
290
291
292

   In this case, Django will create and keep a test database called
   ``test.sql3`` on your current directory. You may delete it when you're done.

André Anjos's avatar
André Anjos committed
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
.. _snapshot:

Local Development Server
------------------------

It is easy to quickly setup a local system for development, taking as base the
current state of a production system.


1. Before starting, make sure you have gone through, at least once, over the
   localhost_ instructions above. It explains the very basic setup required for
   a complete development environment.


2. Dump and back-up your current **production** BEAT database::

     [production]$ ./bin/django backup


3. [Optional] If you have made important modifications between the contents
   available at your production server and your currently checked-out source,
   you'll need to run Django migrations on data imported from the production
   server. If you need to do this, make sure you don't have unapplied commits
   to your local **development** package and reset it to the production tag::

     [development]$ git checkout <production-tag>

   .. note::

      You can figure you the production tag by looking at the footer of the
      BEAT website. The corresponding tag name is found by prefixing a ``v``
      before the version number. For example, the tag for version ``0.8.2`` of
      the platform is ``v0.8.2``.


   Also make sure to revert all dependent packages, so as to recreate the state
   of the database schema as on the production site.


4. Remove the current local development database so that the restore operation
   can start from scratch::

335
     [development]$ rm -rf django.sql3 prefix
André Anjos's avatar
André Anjos committed
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391


5. Copy the backup tarball from the production server and restore it locally::

     [development]$ scp root@beatweb:backups/<backup-filename>.tar.bz2
     [development]$ ./bin/django restore <backup-filename>.tar.bz2

   At this point, you have recreated a copy of your production system locally,
   on your SQLite3 database.


6. Reset queue configuration to allow for local running.

   You may, optionally, reset the queue configuration of your installation so
   that the environment you have is compatible with your development machine,
   so that you can immediately run experiments locally. To do so, use the
   ``qsetup`` Django command::

     [development]$ ./bin/django qsetup --reset


7. Apply migrations::

   $ ./bin/django migrate


At this point, you should have a complete development setup with all elements
available on the production system installed locally. This system is fully
capable of running experiments locally using your machine. Start a full system
using ``localhost.py`` as explained on the localhost_ section above.


Testing Django Migrations
-------------------------

Django migrations, introduced in version 1.7, is a useful feature for
automatically migrating your database to new model schemas, if you get it
right. Here is a recipe to make sure your migrations will work on your
production system, allowing for quick and repetitive test/fix cycles.

The key idea is that we follow the setup for the snapshot_ and then,
locally backup our database and prefix so that we can quickly reproduce the
migration test loop.


1. Make sure you go through the snapshot_ instructions above (**up to
   step 6 only**).


2. Make a copy of the SQLite3 database::

     $ cp -a django.sql3 django.sql3.backup

   This backup will allow you to quickly test the migrations w/o having to
   checkout the production version anymore.

392
   Also, create a temporary git repository of ``prefix``, so you can
André Anjos's avatar
André Anjos committed
393
394
   cross-check changes and reset it in case of problems::

395
     $ cd prefix
André Anjos's avatar
André Anjos committed
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
     $ git init .
     $ git add .
     $ git commit -m "Initial commit"
     $ cd ..


3. Go back to the HEAD or branch you were developping before::

     $ git checkout HEAD


4. Here is how to test/fix your migrations:

   a. Run "django migrate"::

        $ ./bin/django migrate

   b. Check your database by visually inspecting it on the django web admin or
      by manually dumping it.

   c. If a problem is detected, fix it and revert the state::

        $ cp -af django.sql3.backup django.sql3
419
        $ cd prefix && git reset --hard HEAD && git clean -fdx . & cd ..
André Anjos's avatar
André Anjos committed
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456

      .. note::

         Tip: Write the above lines in a shell script so it is easy to repeat.

      Go back to a. and restart.


Javascript Management with Node.js/Bower
----------------------------------------

We manage javascript external packages with the help of Bower_. If you'd like
to include more packages that will statically served with the Django web app,
please consider including them at the appropriate section of ``buildout.cfg``.

The included recipes will also download and install executables for
``uglifyjs``, ``grunt``, ``csslint`` and ``jshint``, which can be useful for JS
development.


Issues
------

If you find problems concerning this package, please post a message to our
`group mailing list`_. Currently open issues can be tracked at `our gitlab
page`_.

.. Place here references to all citations in lower case

.. _django documentation: https://docs.djangoproject.com
.. _pip: http://pypi.python.org/pypi/pip
.. _easy_install: http://pypi.python.org/pypi/setuptools
.. _zc.buildout: http://pypi.python.org/pypi/zc.buildout
.. _virtualenv: http://pypi.python.org/pypi/virtualenv
.. _group mailing list: https://groups.google.com/d/forum/beat-devel
.. _our gitlab page: https://gitlab.idiap.ch/biometric/beat.web/issues
.. _bower: http://bower.io