doc/toWiki/UPGRADE_INDICO_PRODUCTION_CERN

   1 Upgrade of the Indico package on the production machine
   2 =======================================================
   3
   4 0. Purpose of this document
   5
   6 The aim of this document is trying to describe and stablish a standard
   7 procedure which should be followed when upgrading the Indico sw which is
   8 running for production at CERN.
   9 Aspects about third party component installation and maintenance are not
  10 covered here as they are already described in another document [2].
  11
  12 1. Current Indico infrastructure at CERN
  13
  14 Nowadays, Indico system is running at CERN for production purposes (some
  15 conferences are already using it for real) at one single machine:
  16 pcdh94.cern.ch.
  17 Another machine, pcdh91.cern.ch, holding exactly the same system as the
  18 production one runs an Indico prototype having the last features even if this
  19 involves non-stable releases. This is a development machine which can be used
  20 for testing purposes so the upgrading procedure can be tested before doing so
  21 in the production one. This machine should always have the same system (linux
  22 kernel, apache, mod_python, python,  python 3rd party modules) as the
  23 production one.
  24
  25
  26 2. Considerations before upgrading
  27
  28 Upgrading the Indico production system is a very sensitive process and specially
  29 delicated because on one side Indico is living in the same machine (and using
  30 the same HTTP server) other very important production system is running (CDS
  31 Agenda); on the other side, it is a system which is being used for real (that's
  32 why we call it 'production') so any interruption may cause troubles to people
  33 which need to use the system.
  34 This means that the upgrading process should be done with a lot of care and
  35 attention, always having the possibility to easily restore the old system in
  36 case something goes wrong.
  37 For this purpose, here you are some directives one must follow:
  38     i) Before upgrading the system, please make sure the new one resulting
  39         from an installation process is going to work in the production machine
  40         with the current DB. For this purpose, before tagging a new release of
  41         the system, one must make sure that the new version will work with the
  42         production DB and in the production machine; for the former issue, it
  43         is advisable to make a copy of the production DB and make it run
  44         with the new release; for the later, cdsdev is a machine which should
  45         have exaclty the same system as cdsdoc, so prior to installing to cdsdoc
  46         the upgrading should be done to cdsdev and one must verify everything
  47         works smoothly.
  48
  49
  50 3. How to generate a release distribution
  51
  52 Once we know which release we want to install and we are sure the release will
  53 cause no problem in the production server, an installation distribution must
  54 be created. Currently there is no special upgrading procedure; all we have to do
  55 is installing the new release as it was a new system.
  56 In order to generate a release distribution we must use the "distutils" [1]
  57 setup script provided with Indico (can be found in indico/code/dist/setup.py).
  58 Please note that the distribution generation procedure still needs to be
  59 improved so it still contains some manual steps that should be automated in
  60 the future.
  61 These steps must be followed in order to generate a new distribution package:
  62     i) check out in your machine the module "indico/code" related with the
  63         tag associated with the release for which you want to generate the
  64         distribution.
  65     ii) edit the file "indico/code/code/MaKaC/common/general.py" and make sure
  66         the variable "DEBUG_ERRORS" is set to "1" or "True".
  67     iii) copy inside the directory "indico/code/code" the directory
  68         "indico/code/resources/images" and its contents.
  69     iv) copy inside the directory "indico/code/code" the files:
  70             "indico/code/dist/README"
  71             "indico/code/dist/MANIFEST.in"
  72             "indico/code/dist/setup.py"
  73             "indico/code/dist/MaKaCConfig.src"
  74     v) edit the file "indico/code/code/setup.py" and change the version
  75         number (invocation to "setup" function, parameter "version") to the one
  76         you are generating.
  77     vi) run the "indico/code/code/setup.py" script with parameters
  78         "sdist --format=tar" (i.e. indico/code/code/setup.py sdist --format=tar).
  79     vii) the new distribution can be found in
  80         "indico/code/code/dist/MaKaC-X.X.X.tar" corresponding "X.X.X" to the
  81         version number for which the distribution was generated.
  82
  83
  84 4. How to install a new release
  85
  86 Please, remember that before installing a new release in the production server
  87 it must be fully tested and one must be sure that the installation will cause
  88 no trouble in the production machine with the production DB.
  89 Once a distribution has been generated for the version we want to install, the
  90 following steps must be followed:
  91     i) copy the Indico distribution package to production machine (cdsdoc).
  92     ii) untar the distribution (tar -xvf).
  93     iii) edit the MaKaC-X.X.X/setup.py and set the following variables:
  94             htdocsDir = "/soft/httpd/host/indico/htdocs/"
  95             archiveDir = "/data04/MaKaC/archive"
  96             tempUploadedFilesDir = "/tmp"
  97     iv) edit the MaKaC-X.X.X/MaKaCConfig.src and set the configuration
  98         parameters as they currently are in the current Indico configuration
  99         file
 100         (/soft/python/lib/python2.3/site-packages/MaKaC/common/MaKaCConfig.py).
 101         Nowadays they should be set as follows:
 102             DB_params = ("cdsdoc.cern.ch", 9675)
 103             URL_base = "http://indico.cern.ch"
 104             supportEmail = "indico-project@cern.ch"
 105             XMLAbstractPath = "/data04/bk/"
 106     v) having root privileges, execute MaKaC-X.X.X/setup.py script using
 107         "install" as parameter (sudo /soft/bin/python2.3 setup.py install).
 108     vi) restart Apache HTTP server (sudo /soft/bin/apache-ctl restart).
 109 Important: It is quite advisable to make a copy of the current MaKaC package
 110     before installing (step v) the new one just in case something goes wrong
 111     (although this should never happen as the distribution must be tested
 112     before installing) with the installation and the system doesn't work. For
 113     doing this you must copy (having root privileges) the directories
 114     /soft/httpd/host/indico/htdocs/ and
 115     /soft/python/lib/python2.3/site-packages/MaKaC to a local place and restore
 116     them immediately if something goes wrong after the new installation so the
 117     problem can be investigated in other machine without interrupting the
 118     production system.
 119
 120
 121 5. References
 122
 123 [1] "Installing Python Modules" by Greg Ward
 124         <http://python.org/doc/current/inst/inst.html>
 125 [2] "Indico at CERN maintenance guide"
 126
 127