README

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