federation/readme.txt

   1 ==== requirements
   2 you need to have
   3 (*) one master test machine (abbreved 'test') - this is where you
   4 trigger everything from
   5 (*) two servers with myplc installed (abbreved 'plc1' and 'plc2')
   6 at this stage the myplc configuration needs to be done by hand
   7 you also need root ssh access from the test box to the two plc boxes in both boxes
   8
   9 -- configuring the plc servers:
  10 (*) set their names in the Makefile (PLC1 and PLC2)
  11 (*) edit TestPeers.py too -- xxx should be improved
  12
  13 To some extent this stuff can be ran to control a single plc.
  14
  15 ==== concepts
  16 right now, 4 tests sizes are supported, they are named
  17 * m (minimal)      1 object of each kind is created
  18 * n (normal)       a few of each kind
  19 * b (big)                  a few hundreds
  20 * h (huge)         a few thousands
  21
  22 two modes are supported:
  23
  24 (1) single run mode: everything is ran from the 'test' box
  25 this is a convenient, but very slow mode, especially for large sizes
  26 because each individual object is created in a single xmlrpc command
  27 >>> xxx btw, I did not know about begin/commit at that time, but I do not
  28        think it can speed up to the point where the second mode does
  29 In this mode, both DB's are populated together, and various checks can
  30 be done on the fly
  31
  32 (2) populate-and-run mode
  33 where the DB populating parts are done beforehand, and separately,
  34 from each plc's chroot jail for direct access to the DB
  35 This mode allows for dump&restore of the populated DB
  36
  37 ==== preparation
  38
  39 (*) manually install both myplc, do the configs manually (once and for
  40 good, see upgrades below)
  41
  42 (*) initial setup
  43 - check Makefile and TestPeers.py for correct identification of
  44
  45 (*) push the stuff
  46 $ make push
  47 so the local repository gets synced on all nodes.
  48
  49 (*) get and push peers information
  50 $ make peers
  51 (at least once) so the gpg and other authentication materials get pushed to both nodes
  52
  53 ==== use cases
  54
  55 IMPORTANT:  for cleaning up previous tests if needed
  56
  57 $ make db-clean.3
  58 => cleans up both databases if needed
  59 <<< xxx this uses the initscripts to perform the job, it's a bit slow on
  60 old boxes, could probably be improved by snapshotting the db right
  61 after plc gets started>>>
  62
  63 (1)
  64
  65 $ make testpeers.help
  66
  67 $ make testpeers-m.run
  68 assumes the dbs are clean, and runs the test locally
  69
  70 $ make testpeers-b.all
  71 cleans both dbs and runs .run
  72
  73 $ make testpeers-m.diff
  74 checks the output agaist the .ref file that chould be under subversion
  75
  76 $ make testpeers-m.ckp
  77 adopts the current .out as a reference for that test - does *not*
  78 commit under subversion, just copies the .out into .ref
  79
  80 (2)
  81
  82 $ make populate.help
  83
  84 $ make populate-m.all
  85 cleans both dbs, cleans any former result, then runs .init and .run
  86
  87 $ make populate-b.init
  88 assumes both dbs are clean, populates both databases and dumps database in the .sql files
  89
  90 $ make populate-b.run
  91 performs the populate_end part of the test from the populated database
  92
  93 $ make populate-b.restore
  94 restores the database from the stage where it just populated
  95
  96 $ make populate-b.clean
  97 cleans everything except the sql files
  98
  99 $ make populate-b.sqlclean
 100 cleans the .sql files
 101
 102 ==== various utilities
 103
 104 (*) upgrading both plcs (xxx could be improved):
 105 - log as root on both plc servers and manually curl the myplc rpm you
 106 want, in /root/new_plc_api/tests
 107 - back to the server node:
 108 $ make upgrade.3
 109
 110 if you want to upgrade only one, of course just use targets upgrade.1
 111 or upgrade.2
 112
 113 (*) cleaning the database
 114 $ make db-clean.1 (or .2 or .3)
 115
 116
 117
 118 ==== implementation notes
 119 I've designed this thing so everything can be invoked from the test
 120 server, even when things need to be actually triggered from a chroot
 121
 122 For this reason the same pieces of code (namely Makefile and
 123 TestPeers.py) needs to be accessible from
 124 (*) the test server
 125 (*) root's homedir on both plc's, namely in /root/new_plc_api/tests
 126 (*) chroot jail on both plc's, namely in /plc/root/usr/share/plc_api/tests
 127
 128 This is where the 'push' target comes in
 129 xxx at this stage the push target pushes the whole API, because I used this
 130 to test the code that I was patching on the test node. this can be improved
 131
 132 TARGET structure
 133
 134 If you need to invoke something on a given plc, append '.1' or '.2' to the target name
 135 $ make db-clean.1
 136 Will run the 'db-clean' target on the plc1 node
 137
 138 for convenience:
 139 $ make db-clean.3
 140 will run db-clean on both plc's
 141
 142 When something needs to be ran in the chroot jail, run
 143 $ make sometarget.chroot
 144 that will make sometarget from the chroot jail
 145
 146 So from the test server
 147 $ make sometarget.chroot.3
 148 runs in both chroot jails
 149