1 This file documents the contents of this module
3 Last update 4 sept. 2013
5 See the devel/ subdir for more devel-oriented doc.
7 ==================== 1 minute howto
9 * REQUIREMENTS is to have python + django (1.5.2) installed django
10 ** should be straightforward
11 ** see devel/django-install.txt in case of trouble
13 * git clone git://git.onelab.eu/myslice.git
15 * git clone ssh://yourlogin@git.onelab.eu/git/myslice.git
17 * edit myslice/config.py and enter the details of your manifold backend
24 $ ./manage.py collectstatic (formerly, we used make static, which is deprecated)
26 $ ./manage.py collectstatic --noinput
28 * gather templates files
29 for now we still seem to rely on a make-based templates-collection process
30 that creates all-templates/
34 $ manage.py runserver 0.0.0.0:8000
36 $ devel/server-loop.sh
37 when you just need to hit ^C yourself when your static files need to be refreshed - see below
39 * use it from your browser
40 (See more notes on using the development server below)
42 * install dependencies
43 $ pip install -r path/to/requirements/file.txt
44 Note. not quite sure what this is about, I could not spot this file..
46 ==================== Status
48 *** Authentication ***
51 Not quite sure if/how the user gets proper notifications when
52 . his session has expired (i.e. his frontend is not logged into the backend any longer)
53 . his credentials have expired (i.e. the uploaded credentials, e.g. SFA delegated cred)
54 expired and she needs to run e.g. sfi myslice again
56 Hard-coded accounts (from a very early stage) are gone
61 I've done a very rough attempt at packaging for rpm.
62 The logic seems about right but needs more work, in particular in terms of installing myslice.conf
63 in the httpd conf.d directory.
64 It seems like our app won't work on f14 as is because Django is only 1.3.1 on f14
65 Plan is to target f18 but I lack a test machine.
66 Also of course I'll try to tackle debian/ubunti at some point.
68 There also is a working packaging for debian(s) and ubuntu(s) that we use
69 on an almost daily basis to upgrade manifold.pl.sophia.inria.fr
74 Third party tools shipped:
81 Others are added as we build the system when they become needed
82 Look in third-party/ for a more detailed list
84 As a rule of thumb, please try to keep in mind that these will need to
85 be upgraded over time I've tried to keep track of the version I picked
86 and to have an easy upgrade path (depending on the way the original
89 ==================== Contents: 1st level subdirs
91 ========== code from git
94 this is the django 'project', where to look for
99 the code for dealing with queries, sending them to the backend, and offering the /manifold/proxy/ URL
102 the code for building / rendering plugins
105 the actual code for plugins
108 a django 'app' that deals with authentication; see especially
109 auth.backend.MyCustomBackend
110 for how to use a separate authentication system,
111 as well as settings.py for how to enable it
114 this is where the first implementation of myslice, with complete
115 user-management including registration, is taking place
118 rough/preliminary scaffolding views are in here
119 as the name suggests this is temporary
122 will receive actual views over time
123 currently has some global html templates as well
124 + some global static files (css, js, images..)
127 a third-party django app for adding on-the-fly mentions to css or js files that need to go in the header
130 * third party javascript and css stuff (bootstrapfs, jquery, this kind of things)
131 see more about that below too
134 no code in there, only various notes and other scripts useful for developers
136 ========== automatically generated
138 * static/: (generated by collectstatic, see above, do not source-control)
139 $ manage.py [ --noinput ] collectstatic
144 this is where django stores its own stuff, as per settings.py
146 ==================== conventions for templates & static files
147 ==================== and NOTES on using the development server
149 . first off, running manage.py runserver is provided by django as a development convenience but
150 SHOULD NOT be used in production
152 . second, when you do use it for developement purposes, please be aware that:
154 .. the recommended layout for the various files and pieces (py, html, js and css) with django is
155 IMHO really painful; we *SHOULD* use e.g.
156 plugins/quickfilter/quickfilter.py,
157 plugins/quickfilter/templates/quickfilter.html,
158 plugins/quickfilter/static/js/quickfilter.js
159 plugins/quickfilter/static/css/quickfilter.css
160 which I have tried doing for a while but I found myself just hopping around in the file tree all
161 day long, wasting cycles big time
163 .. as that does not make sense IMHO, I've rewritten the tool for gathering these pieces (this is in
164 the Makefile). Bottom line is we can essentially store this wherever we want.
165 The only restriction being that if you have a template that is *not* html, then it *has to* sit
166 in a templates/ directory, otherwise it gets shipped as a static file.
168 .. as a result, we can now store all the files building a plugin in a single (git) directory; like e.g.
169 plugins/quickfilter/quickfilter.py
170 plugins/quickfilter/quickfilter.html
171 plugins/quickfilter/quickfilter.js
172 plugins/quickfilter/quickfilter.css
174 Of course it's a completely different matter once the service is packaged and installed, these
175 files of course get properly separated.
177 .. as a result it is a little bit less convenient to use the development server when you change the
178 layout of your static and template files, you might need to re-run 'make static', so it is
179 recommended to use devel/server-loop.sh instead
182 All this being said, here are our current conventions for storing templates and static files
185 we store this under templates/ within the corresponding app, e.g.
186 auth/templates/login.html
187 for now this is mostly about html, but the engine can be used for rendering anything
188 including js(on) or whatever (in which case, as stated above, this *must* have /templates/ in its path.
191 we chose to have all static files (images, but also javascript and stylesheets) in the various
192 proj or app where they belong, with a layout like:
197 Honestly it's not yet very clear sometimes what 'where-it-belongs' should be sometimes, and it
198 does not matter too much anyway, given that the code doesn't need to change when we move things
199 around. So in particular it's fuzzy between myslice/ (where the logo could fit e.g.) views/ and
202 Makefile has a few convenience targets to list all kinds of stuff; the 2 major targets are
204 $ make static templates
206 that would reset all-static/ and all-templates/ for you from the other contents
209 please note that the set of files that actually get exposed in all-static from third-party is
210 hand-coded in Makefile because we tried to preserve the original codebase layout from mainstream,
211 and there's only so much in common between 2 differents js libraries at this point.
215 ======== update django database to reflect changes in existing models without any migration system (e.g., south) =========
218 $python manage.py reset <your_app>
220 #Django 1.5.1 or later
221 $python manage.py flush
223 This will update the database tables for your app, but will completely destroy any data that existed in those tables.
224 If the changes you made to your app model do not break your old schema (for instance, you added a new, optional field)
225 you can simply dump the data before and reload it afterwards, like so:
227 $python manage.py syncdb
228 $python manage.py dumpdata <your_app> > temp_data.json
229 $python manage.py flush
230 $python manage.py loaddata temp_data.json
232 If your changes break your old schema this won't work - in which case tools like south or django evolution are great.
234 ======== update django database to reflect changes in existing models with migration system (e.g., south) =========
236 As south is already installed , you just have to do:
242 1. go to myslice directory
243 2. do sqlite3 myslice.sqlite3 [if sqlite3: command not found, do $apt-get install sqlite3]
244 3. check the list of tables with sqlite> .tables
245 4. if you find those tables that was mentioned in the failure message while running $./manage.py migrate
246 do sqlite> DROP TABLE mentioned_table
247 [mentioned_table = the tables that was explicity mentioned in the failure message of $./manage.py migrate]
249 6. $./manage.py migrate