doc/toWiki/distribution

   1 INDICO Distribution Guide (Developers)
   2
   3 CERN
   4
   5 -------------------------------------------------------------------------------
   6
   7 Table of Contents
   8 1. Distributing the MaKaC package
   9
  10     1.1. To add files to be distributed
  11     1.2. To add packages to be distributed
  12     1.3. To add files to be installed
  13
  14 2. Explanation of the XML Configuration File 'config.xml'
  15
  16     2.1. Path Directories
  17     2.2. Database, Url, Email, SMTP and OAI Parameters
  18     2.3. File Types and System Icons
  19
  20 3. Adding parameters or paths to the XML configuration file
  21
  22     3.1. Adding new File Type or System Icon
  23     3.2. Adding a new Path parameter
  24     3.3. Adding a new Stylesheet parameter
  25     3.4. Adding a new OAI parameter
  26     3.5. Adding a new Database parameter
  27     3.6. Adding any other parameters
  28
  29 4. How the whole Installation process works
  30
  31     4.1. How Distributing works (setup.py sdist)
  32     4.2. How the Install works (setup.py install)
  33     4.3. What the upgrade does (setup.py upgrade)
  34     4.4. What reconfiguring does (reconfigure.py run)
  35
  36 -------------------------------------------------------------------------------
  37
  38 Chapter 1. Distributing the MaKaC package
  39
  40 To Distribute the MaKaC package:
  41
  42  1. You need to run the distribution from the Indico root directory, a version
  43     number is needed and a format type is optional.
  44
  45  2. You need to specify the version number that you are distributing, you can
  46     either do this by:
  47
  48      a. Specifying the version number as an option when running the
  49         distribution by using:
  50         setup.py sdist --version x.x.x
  51         Where x.x.x is the version number
  52
  53      b. Enter the version number when asked and just run the distribution with:
  54         setup.py sdist
  55
  56  3. If you want a specific format type for example a .tar you need to specify
  57     this otherwise the format type will be the defaulf for the platform, to
  58     specify a format type:
  59     setup.py sdist --format=tar
  60     This can be done before or after the --version option and in either order,
  61     i.e.
  62     setup.py sdist --version x.x.x --format=tar
  63
  64 The distribution will be in the dist folder and be called MaKaC-x.x.x.tar,
  65 depending on the version number and format type you gave
  66
  67 -------------------------------------------------------------------------------
  68
  69 1.1. To add files to be distributed
  70
  71 If you want to add any extra files to be distributed with the package, you just
  72 need to add the file name and location to the 'manifest.in' file. For example
  73 if you want to distribute a file called script.py which is in the 'dist'
  74 folder, in the manifest file you can write:
  75  include dist/scrip.py
  76
  77 -------------------------------------------------------------------------------
  78
  79 1.2. To add packages to be distributed
  80
  81 If you want to add any extra packages to be distributed, you need to edit the
  82 setup() function in the setup.py script, you need to add the name of the
  83 package into the 'packages' section, e.g.
  84 packages=['MaKaC', 'MaKaC.authentication',\
  85         'MaKaC.common', 'MaKaC.export', 'MaKaC.webinterface',\
  86         'MaKaC.webinterface.pages', 'MaKaC.webinterface.rh',\
  87         'MaKaC.webinterface.session', 'MaKaC.webinterface.common',\
  88         'MaKaC.PDFinterface', 'MaKaC.ICALinterface'],
  89 Your package name needs to go into the end of this list
  90
  91 -------------------------------------------------------------------------------
  92
  93 1.3. To add files to be installed
  94
  95 If you want to add any files to be installed that are not inside the packages
  96 mentioned above you need to specify the file names and the location you want
  97 them to go in, e.g.
  98 data_files=[(x.tplDir, TPLFileList()),\
  99                   (x.htdocsDir, HTDOCFileList()),\
 100                   (x.ssDir, SSFileList()),\
 101                   (x.imageDir, IMGFileList()),
 102                   (x.confdef,['config.xml','dist/config.xsd',\
 103                               'reconfigure.py','dist/confmerge.py'])]
 104 The format to add the files is (location,file).
 105
 106 -------------------------------------------------------------------------------
 107
 108 Chapter 2. Explanation of the XML Configuration File 'config.xml'
 109
 110 2.1. Path Directories
 111
 112 Numbered Sections may not been in the same order in the actual config.xml file
 113
 114 <!--Enter Path names in between the pathdir tags, e.g.<pathdir>c:\tmp</pathdir>
 115 or leave blank for default-->
 116
 117         <paths>
 118 (1)   <pathname>pkgdirectory</pathname>
 119             <pathdir></pathdir>
 120         </paths>
 121
 122         <paths>
 123 (2)   <pathname>htdocs</pathname>
 124             <pathdir></pathdir>
 125         </paths>
 126 <!--htdocs needs to be the same directory as where you set the modpython handler
 127 (or blank)-->
 128
 129         <paths>
 130 (3)   <pathname>archive</pathname>
 131             <pathdir></pathdir>
 132         </paths>
 133
 134         <paths>
 135 (4)   <pathname>temp</pathname>
 136              <pathdir></pathdir>
 137         </paths>
 138
 139         <paths>
 140 (5)   <pathname>tpls</pathname>
 141     <pathdir></pathdir>
 142         </paths>
 143
 144 <paths>
 145 (6)   <pathname>ssheets</pathname>
 146     <pathdir></pathdir>
 147         </paths>
 148
 149
 150
 151 (1) The main package directory, this is where the main package files for the
 152     Indico program will be put, under a folder called Makac.
 153 (2) The htdocs directory, this directory holds the webpage files for the
 154     webinterface.
 155 (3) The archive directory, multimedia files from the conferences will be stored
 156     in this directory.
 157 (4) The temporary directory, files being uploaded and any other temporary files
 158     will be stored into this directory, Note: This directory needs to have a
 159     fair amount of space available.
 160 (5) The templates directory, templates for the webinterface are kept in this
 161     directory.
 162 (6) The stylesheets directory, the stylesheets are stored in this directory
 163
 164 -------------------------------------------------------------------------------
 165
 166 2.2. Database, Url, Email, SMTP and OAI Parameters
 167
 168 <!--Enter database parameters in between tags, e.g. <port>1234</port>
 169 or leave as they are for default-->
 170
 171         <db_param>
 172      (1)     <host>localhost</host>
 173      (2)     <port>9675</port>
 174         </db_param>
 175
 176
 177
 178
 179 <!--Enter url base in between tags, e.g. <url>http://localhost/MaKaC</url>
 180 or leave as it is for default-->
 181
 182
 183      (3)        <url>http://localhost/MaKaC</url>
 184
 185
 186
 187 <!--Enter support email in between tags, e.g. <email>indico-project@cern.ch</email>
 188 or leave for default-->
 189
 190
 191      (4)        <email>indico-project@cern.ch</email>
 192
 193
 194 <!--Enter SMTP Server to send Email or leave for default-->
 195
 196      (5)        <smtp>smtp.cern.ch</smtp>
 197
 198
 199
 200 <!--OAI Parameters, leave for default -->
 201
 202       (6) <OAI>
 203              <logfile>/tmp/oailog.log</logfile>
 204              <nb_record>100</nb_record>
 205              <nb_ids>100</nb_ids>
 206              <oai_rt_exp>90000</oai_rt_exp>
 207              <namespace>eAgora.cern.ch</namespace>
 208              <iconfNS>URL_base</iconfNS>
 209              <iconfXSD>URL_base+"/iconf.xsd"</iconfXSD>
 210              <reposName>eAgora</reposName>
 211              <reposId>eAgora.cern.ch</reposId>
 212        </OAI>
 213
 214
 215 (1) The database host, this parameter holds the location of the host that the
 216     database is stored on.
 217 (2) The database port, this parameter holds the port number of which to contact
 218     the database.
 219 (3) The Base Url, the url from which Indico can be reached from a web browser.
 220 (4) The support email, the email address for people to contact with support
 221     issues.
 222 (5) The smtp server, the server to allow emails to be sent out.
 223 (6) The OAI parameters, these are for configuring the open archive interface.
 224
 225 -------------------------------------------------------------------------------
 226
 227 2.3. File Types and System Icons
 228
 229 <!--Known file types-->
 230
 231 (1) <FileType>
 232             <type>DOC</type>
 233             <name>Ms Word</name>
 234             <loc>application/msword</loc>
 235             <img>doc.gif</img>
 236           </FileType>
 237
 238 <!-- System Icons -->
 239
 240 (2)     <SysIcon>
 241              <icon>modify</icon>
 242              <pic>link.gif</pic>
 243           </SysIcon>
 244
 245 <!-- Stylesheets-->
 246
 247
 248 (3)   <event>
 249           <eventname>simple_event</eventname>
 250               <sheets>
 251                         <view>static</view>
 252                         <style>static</style>
 253               </sheets>
 254     </event>
 255
 256
 257 <!-- Default Stylesheets -->
 258
 259 (4) <defaultss>
 260                 <eventid>simple_event</eventid>
 261                 <sheet>lecture</sheet>
 262    </defaultss>
 263
 264
 265 (1) FileTypes, These specify the different file types and the name, location
 266     and image associated with them that are available within Indico.
 267 (2) System Icons, These specify the icon name and the image associated with
 268     them.
 269 (3) Stylesheets, These specify the stylesheets available for each event with
 270     the event name, view and stylesheet.
 271 (4) Default Stylesheets, These specify the default stylesheet for each event
 272     with the event name and stylesheet.
 273
 274 -------------------------------------------------------------------------------
 275
 276 Chapter 3. Adding parameters or paths to the XML configuration file
 277
 278 If parameters or paths need to be added to the config.xml file so the user can
 279 customise them they can be added depending on what paramter they are:
 280
 281 -------------------------------------------------------------------------------
 282
 283 3.1. Adding new File Type or System Icon
 284
 285 To add a new file type or system icon you just need to add another tag to the
 286 xml file
 287
 288  1. FILE TYPE: To add a File Type just add a FileType tag which has type, name,
 289     loc and img tags inside it to the bottom of the File Type section, e.g.:
 290             <FileType>
 291                         <type>PPT</type>
 292                         <name>Ms Powerpoint</name>
 293                         <loc>application/vnd.ms-powerpoint</loc>
 294                        <img>ppt.gif</img>
 295             </FileType>
 296
 297  2. SYSTEM ICON: To add a System Icon just add a SysIcon tag which has icon and
 298     pic tags inside it to the bottom of the System Icons section, e.g.:
 299             <SysIcon>
 300                    <icon>modify</icon>
 301                    <pic>link.gif</pic>
 302             </SysIcon>
 303
 304 Both the File Types and System Icons are stored in dictionarys in the setup.py
 305 file called 'types' and 'systemicons'
 306
 307 -------------------------------------------------------------------------------
 308
 309 3.2. Adding a new Path parameter
 310
 311 To add a new Path parameter you just need to add another 'paths' tag which has
 312 pathname and pathdir inside it to the bottom of the paths section, e.g.:
 313         <paths>
 314             <pathname>archive</pathname>
 315             <pathdir></pathdir>
 316         </paths>
 317
 318 The paths are are stored in the setup.py in a dictionary called 'paths' using
 319 the <pathname> as the key in the example above to get the path directory you
 320 would use paths['archive']
 321
 322 -------------------------------------------------------------------------------
 323
 324 3.3. Adding a new Stylesheet parameter
 325
 326 To add a new Stylesheet parameter you just need to add another 'sheets' tag
 327 (inside the correct events section) which has view and style inside it to the
 328 bottom of the stylesheets section, e.g.:
 329         <sheets
 330             <view>static</view>
 331             <style>static</style>
 332         </sheets>
 333
 334 The stylesheets are stored in a dictionary in setup.py call 'stylesheets' with
 335 eventname as the first key and view as the second key.
 336
 337 To add a new Default Stylesheet parameter you just need to add another
 338 'defaultss' tag which has eventid and sheet inside it to the bottom of the
 339 default stylesheets section, e.g.:
 340         <defaultss>
 341             <eventid>meeting</eventid>
 342             <sheet>standard</sheet>
 343         </defaultss>
 344
 345
 346 The stylesheets are stored in a dictionary in setup.py call 'dss' with eventid
 347 as the key .
 348
 349 -------------------------------------------------------------------------------
 350
 351 3.4. Adding a new OAI parameter
 352
 353 To add a new OAI paramter:
 354
 355  1. You need to add the name of the parameter as a tag to the end of the OAI
 356     section, e.g.:
 357             <OAI>
 358                    <logfile>/tmp/oailog.log </logfile>
 359                    <nb_record>100 </nb_record>
 360                                 ...
 361                    <reposName>eAgora </reposName>
 362                    <reposId>eAgora.cern.ch </reposId
 363                    New tag would go here e.g. <new>value</new>
 364             </OAI>
 365
 366  2. In the config handler file 'confmerge.py', Parser() Class, you need to add
 367     the name of your tag into the list of 'if name in' inside the relevant
 368     section of the end element function
 369
 370  3. You also need to add the new tag into the config schema 'config.xsd' add
 371     the following line into the OAI section of the schema:
 372     <xs:element name="NEWTAG" type="xs:string" />
 373     Replace NEWTAG with the name of the tag you added
 374
 375  4. Validate that the schema and the xml file conicide with each other and
 376     validate correctly, you can use: http://apps.gotdotnet.com/xmltools/
 377     xsdvalidator/Default.aspx
 378
 379 The OAI parameters are stored in setup.py in a dictionary called 'OAI' using
 380 the tagname as the key e.g. OAI['logfile']
 381
 382 -------------------------------------------------------------------------------
 383
 384 3.5. Adding a new Database parameter
 385
 386 To add a new database parameter you need to follow a similar process as for
 387 adding an OAI parameter the only differences are where the tags go:
 388
 389  1. Add the name of the parameter to the end of the db_param section:
 390             <db_param>
 391                   <host>localhost</host>
 392                   <port>9675</port>
 393             New tag would go here e.g. <new>value</new>
 394             </db_param>
 395
 396  2. In the config handler file 'confmerge.py', Parser() function, you need to
 397     add the name of your tag into the list of 'if name in' inside the relevant
 398     section of the end element function
 399
 400  3. You also need to add the new tag into the config schema 'config.xsd' add
 401     the following line into the db_param section of the schema:
 402     <xs:element name="NEWTAG" type="xs:string" />
 403     Replace NEWTAG with the name of the tag you added
 404
 405  4. Validate that the schema and the xml file conicide with each other and
 406     validate correctly, you can use: http://apps.gotdotnet.com/xmltools/
 407     xsdvalidator/Default.aspx
 408
 409 The database parameters are stored in setup.py in a dictionary called
 410 'db_params' using the tag name as the key, e.g db_params['host']
 411
 412 -------------------------------------------------------------------------------
 413
 414 3.6. Adding any other parameters
 415
 416 To add any other parameters to the config xml file you need to look at how
 417 current parameters are added and follow these steps:
 418
 419  1. Add the tags to the config.xml file
 420
 421  2. Add the necessary to the config.xsd schema file
 422
 423  3. Validate the schema and xml file: http://apps.gotdotnet.com/xmltools/
 424     xsdvalidator/Default.aspx
 425
 426  4. Capture the data from the xml file using the confmerge.py script
 427
 428  5. Import the dictionary from the handler into setup.py script
 429
 430 -------------------------------------------------------------------------------
 431
 432 Chapter 4. How the whole Installation process works
 433
 434 Brief explanation of how the Installation process works
 435
 436 -------------------------------------------------------------------------------
 437
 438 4.1. How Distributing works (setup.py sdist)
 439
 440 When the 'sdist' command is given the script checks if a version value was
 441 given if not it asks for one, it then writes the version number at the top of
 442 the main __init__ file, and stores the version number for use with the
 443 distribution name. It then copies the config and information files (such as
 444 config.xml and readme) to the front directory so that once distributed the
 445 files are easier for the user to access.
 446
 447 The distribution itself is done by python. Using the manifest.in file and the
 448 setup function in setup.py it knows which files to include in the distribution
 449 and compresses them into a .zip or .tar etc depending on what was asked for.
 450
 451 -------------------------------------------------------------------------------
 452
 453 4.2. How the Install works (setup.py install)
 454
 455 When the 'install' command is given the script writes the MaKaCConfig.py
 456 script, writes the setup.cfg file, writes the reconfigure.py script and then
 457 copies the MaKaCConfig file to the common directory.
 458
 459 The actual install is done by python. It uses the setup.cfg file to know what
 460 directory to install the build from the distribution in to (if its not the
 461 default python site-packages) and then uses the rest of the setup function in
 462 setup.py to install any other data files into the directories specified.
 463
 464 -------------------------------------------------------------------------------
 465
 466 4.3. What the upgrade does (setup.py upgrade)
 467
 468 when the upgrade function in the setup.py script is run it asks the user for
 469 the main package directory or to type default if they did not specify a custom
 470 installation path. The confmerge.py script is then used to merge the old
 471 config.xml file with the new one to obtain any custom settings the user had and
 472 to add any new paramters that may be in the new config.xml file. The user is
 473 asked to check the configurations are correct and to then run the install
 474 command. This saves the user from having to rewrite all their configurations
 475 each time they want to install a new version.
 476
 477 -------------------------------------------------------------------------------
 478
 479 4.4. What reconfiguring does (reconfigure.py run)
 480
 481 When the user wants to reconfigure their installation, from the /common
 482 directory in the MaKaC installation they can change the config.xml file and
 483 then run the reconfigure script. The reconfigure script was generated when the
 484 first install was made and this reconfigure script just contains the same code
 485 from setup.py but only the functions that generated the MaKaCConfig script. So
 486 when run it takes the new config.xml and creates a new MaKaCConfig file from
 487 that.
 488