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