README

   1 Last update 21 MAY. 2015
   2
   3 Installation
   4 =================================================================
   5 Complete Guide: http://trac.myslice.info/wiki/Manifold/Install
   6
   7 Recommended OS
   8 ===============
   9 Debian GNU/Linux 7.5 (wheezy) x64
  10
  11 PYTHON DEPENDENCIES
  12 =====================
  13 sudo apt-get install python-pip or sudo easy_install pip==1.4.1
  14 sudo apt-get install python-dev (for paramiko and pyOpenSSL)
  15 sudo apt-get install libffi-dev (for pyOpenSSL)
  16
  17 $ pip install django=="1.5.2"
  18 $ apt-get install python-django-south
  19 $ pip install requests
  20 $ pip install djangorestframework
  21 $ pip install django-celery
  22 $ pip install geopy
  23 $ pip install paramiko
  24 $ pip install pyparsing
  25 $ pip install python-dateutil
  26 $ pip instal pyOpenSSL
  27 $ pip install xmltodict
  28
  29 MYSLICE
  30 =======
  31 git clone ssh://yourlogin@git.onelab.eu/git/myslice.git
  32 cd myslice
  33 git checkout onelab
  34
  35 edit/create myslice/myslice.ini and enter the details of your manifold backend
  36
  37 $ ./manage.py syncdb
  38 $ ./manage.py migrate
  39 $ ./manage.py collectstatic
  40
  41 Run the development server
  42 $ ./devel/server-loop.sh
  43
  44 MANIFOLD
  45 ==========
  46 git clone git://git.onelab.eu/manifold.git
  47 cd manifold
  48 git checkout devel
  49 make && make install
  50
  51 SFA
  52 ===
  53 $ git clone -b geni-v3 git://git.onelab.eu/sfa.git
  54 $ cd sfa
  55 $ git checkout geni-v3
  56
  57 $ make version
  58 $ python ./setup.py install
  59
  60 =====================================================================
  61
  62 ## Whenever doing a git pull the following operations are recommended:
  63
  64 $ make static # will refresh static/ from all the pieces in the project
  65 $ make templates # same, for templates
  66 $ make redo-static # clears up (rm -rf) static/ first, then make static
  67 $ make redo-templates # ditto for templates
  68 $ make redo == make redo-static redo-templates
  69
  70
  71 * run a local server:
  72 $ ./manage.py runserver 0.0.0.0:8000
  73 -- or -- my advice:
  74 $ devel/server-loop.sh
  75 when you just need to hit ^C yourself when your static files need to be refreshed - see below
  76
  77 * use it from your browser
  78 (See more notes on using the development server below)
  79
  80 * install dependencies
  81 $ pip install -r path/to/requirements/file.txt
  82 Note. not quite sure what this is about, I could not spot this file..
  83
  84 =====APACHE Config=====
  85 if are running apache please do:
  86
  87 $ chown www-data:www-data /var/myslice-f4f
  88
  89 otherwise you may get the following error:
  90 "DatabaseError: unable to open database file"
  91
  92 ==================== Status
  93
  94 *** Authentication ***
  95
  96 Should be mostly fine
  97 Not quite sure if/how the user gets proper notifications when
  98 . his session has expired (i.e. his frontend is not logged into the backend any longer)
  99 . his credentials have expired (i.e. the uploaded credentials, e.g. SFA delegated cred)
 100   expired and she needs to run e.g. sfi myslice again
 101
 102 Hard-coded accounts (from a very early stage) are gone
 103
 104
 105 *** Packaging ***
 106
 107 I've done a very rough attempt at packaging for rpm.
 108 The logic seems about right but needs more work, in particular in terms of installing myslice.conf
 109 in the httpd conf.d directory.
 110 It seems like our app won't work on f14 as is because Django is only 1.3.1 on f14
 111 Plan is to target f18 but I lack a test machine.
 112 Also of course I'll try to tackle debian/ubunti at some point.
 113
 114 There also is a working packaging for debian(s) and ubuntu(s) that we use
 115 on an almost daily basis to upgrade manifold.pl.sophia.inria.fr
 116
 117
 118 ====================
 119
 120 Third party tools shipped:
 121
 122 * jquery
 123 * datatables
 124 * spin
 125 * bootstrap
 126
 127 Others are added as we build the system when they become needed
 128 Look in third-party/ for a more detailed list
 129
 130 As a rule of thumb, please try to keep in mind that these will need to
 131 be upgraded over time I've tried to keep track of the version I picked
 132 and to have an easy upgrade path (depending on the way the original
 133 package is published)
 134
 135 ==================== Contents: 1st level subdirs
 136
 137 ========== code from git
 138
 139 * myslice/
 140   this is the django 'project', where to look for
 141   . settings.py
 142   . urls.py
 143
 144 * manifold/
 145   the code for dealing with queries, sending them to the backend, and offering the /manifold/proxy/ URL
 146
 147 * unfold/
 148   the code for building / rendering plugins
 149
 150 * plugins/
 151   the actual code for plugins
 152
 153 * auth/
 154   a django 'app' that deals with authentication; see especially
 155   auth.backend.MyCustomBackend
 156   for how to use a separate authentication system,
 157   as well as settings.py for how to enable it
 158
 159 * ui/
 160   provides building blocks for the UI, especially layouts (1 or 2 columns) as
 161   well as the topmenu widget
 162   + some global static files (css, js, images..)
 163
 164 * portal/
 165   this is where the first implementation of myslice, with complete
 166   user-management including registration, is taking place
 167
 168 * trash/
 169   rough/preliminary scaffolding views are in here
 170   as the name suggests this is temporary
 171
 172 * insert_above:
 173   a third-party django app for adding on-the-fly mentions to css or js files that need to go in the header
 174
 175 * third-party/
 176    * third party javascript and css stuff (bootstrapfs, jquery, this kind of things)
 177      see more about that below too
 178
 179 * devel:
 180   no code in there, only various notes and other scripts useful for developers
 181
 182 ========== automatically generated
 183
 184 * static/: (generated by collectstatic, see above, do not source-control)
 185   $ manage.py [ --noinput ] collectstatic
 186
 187 * templates/
 188
 189 * myslice.sqlite3
 190   this is where django stores its own stuff, as per settings.py
 191
 192 ==================== conventions for templates & static files
 193 ==================== and NOTES on using the development server
 194
 195 . first off, running manage.py runserver is provided by django as a development convenience but
 196   SHOULD NOT be used in production
 197
 198 . second, when you do use it for developement purposes, please be aware that:
 199
 200 .. the recommended layout for the various files and pieces (py, html, js and css) with django is e.g.
 201       plugins/quickfilter/___init__.py,
 202       plugins/quickfilter/templates/quickfilter.html,
 203       plugins/quickfilter/static/js/quickfilter.js
 204       plugins/quickfilter/static/css/quickfilter.css
 205       plugins/quickfilter/static/img/some-image.png
 206
 207 .. the files actually used by the development server are the ones located in
 208  static/
 209  templates/
 210
 211 you can and should use the following make targets to refresh the
 212 contents of these directories when running a developement server
 213 $ make static                 to refresh static/
 214 $ make redo-static            to clean up static/ and then refresh its contents
 215 $ make templates              to refresh templates/
 216 $ make redo-templates         to clean up templates/ and then refresh its contents
 217 $ make redo                   equivalent to make redo-static redo-templates
 218
 219 .. as far as possible, please make sure to use third-party to store
 220 any javascript tool or utility that your plugin depends upon
 221
 222 also we have the convention that all material in third-party should be
 223 tagged with a version number, with a symlink pointing to the version
 224 being used, like this
 225
 226 ~/git/myslice/third-party $ ls -ld spin*
 227 lrwxr-xr-x  1 parmentelat  staff   10 Sep  6 17:55 spin -> spin-1.3.0
 228 drwxr-xr-x  7 parmentelat  staff  238 Sep  6 17:55 spin-1.2.8
 229 drwxr-xr-x  7 parmentelat  staff  238 Sep  6 17:55 spin-1.3.0
 230
 231 finally, as far as possible we keep track of the urls used to pull
 232 stuff in the first place so that upgrades are easier
 233
 234 . third, be careful when importing third party material, to stay away from demo-oriented material
 235
 236 e.g. at some point we were using demo_page.css and demo_table.css from the datatables demo and sample pages
 237 unfortunately these are not tailored for production use as they are setting styles on a very wide scope
 238 that breaks a lot of stuff, so please refrain from using these altogether
 239
 240
 241 ======== update django database to reflect changes in existing models without any migration system (e.g., south) =========
 242
 243 # older version
 244 $python manage.py reset <your_app>
 245
 246 #Django 1.5.1 or later
 247 $python manage.py flush
 248
 249 This will update the database tables for your app, but will completely destroy any data that existed in those tables.
 250 If the changes you made to your app model do not break your old schema (for instance, you added a new, optional field)
 251 you can simply dump the data before and reload it afterwards, like so:
 252
 253 $python manage.py syncdb
 254 $python manage.py dumpdata <your_app> > temp_data.json
 255 $python manage.py flush
 256 $python manage.py loaddata temp_data.json
 257
 258 If your changes break your old schema this won't work - in which case tools like south or django evolution are great.
 259
 260
 261 Add a new model to the DB
 262
 263 $python manage.py schemamigration <your_app> --auto
 264 $python manage.py migrate
 265
 266 ======== update django database to reflect changes in existing models with migration system (e.g., south) =========
 267
 268 As south is already installed , you just have to do:
 269
 270 # ./manage.py schemamigration portal --initial
 271 # sqlite3 /var/unfold/unfold.sqlite3
 272         sqlite> DROP TABLE "portal_institution";
 273         sqlite> DROP TABLE "portal_pendinguser";
 274         sqlite> DROP TABLE "portal_pendingauthority";
 275         sqlite> DROP TABLE "portal_pendingslice";
 276         sqlite> .quit
 277 # ./manage.py migrate portal