Use multimarkdown to convert .md -> .html
[buildfarm-client-wiki.git] / Installation.md
index d0940ecc7483c354e79ae538460baa550e1b841e..26a7f13552692b7a86dc88ec15628aa15066d58c 100644 (file)
@@ -35,17 +35,37 @@ This will create the repo checkout in the directory *~/code/*.
 15. Test the test suite by running `./run_build.pl --test --verbose=2 --only-steps=configure,make,test --override range_num_tests='1 2'`.  There will be one error on a standard system: the Exim test suite uses ifconfig to obtain the IP address, and this binary is frequently not in a regular user's path.  Temporarily fix this by running `export PATH="/usr/sbin:/sbin:$PATH"` to prepend the probably directories where that command is located to your regular user path. (Instructions on how to do this automatically in the cron job are below).  If there are build errors when building the test suite, or runtime errors trying to run the test suite, you may need to install additional packages (you shouldn't though).
 16. If you enabled the documentation building process in the *build-farm.conf*, then you can try to build it with `./run_build.pl --test --verbose=2 --only-steps=configure,make-doc`.  For documentation generation to succeed, it will require extra packages to be installed to support xml, xslt, pdf, and a few other things. Please see the comments on the [Building Documentation](https://github.com/mrballcb/exim-build-farm-client/wiki/BuildingDocs) page.
 17. If you can get past each of these steps, then your build farm system meets the minimum requirements.
-18. The official process can be kicked off by running `/home/farm/code/run_cron.sh --run-all`.  This will run the default build configuration, keep track of the git repository status, and upload the build results to the server.
-19. Once that command runs with no complaints, add it to the **farm** user crontab.  You can run it at whatever frequency you choose, I suggest 1 hour.  If a previous instantiation is still running, the script will detect the lockfile and exit so as not to step on each other.  I had a problem running the *run_cron.sh* script in that cron gives a highly sanitized path to the script when it runs it.  I made a second script to call the first one so I could insert path elements in that were needed:
+18. The official process can be kicked off by running `/home/farm/code/run_cron --run-all`.  This will run the default build configuration, keep track of the git repository status, and upload the build results to the server.
+19. Once that command runs with no complaints, add it to the **farm** user crontab.  You can run it at whatever frequency you choose, I suggest 2 hours.  If a previous instantiation is still running, the script will detect the lockfile and exit so as not to step on each other.  I had a problem running the *run_cron.sh* script in that cron gives a highly sanitized path to the script when it runs it.  I made a second script to call the first one so I could insert path elements in that were needed:
 <pre><code>$ more /home/farm/bin/build_farm.sh
 #!/bin/bash
 export PATH="/usr/local/bin:/sbin:/usr/sbin:$PATH"
 $HOME/code/run_cron.sh --run-all $@
 </code></pre>
-Then I make my cronjob call: `6 * * * * $HOME/bin/build_farm.sh` .... but ...
+Then I make my cronjob call: `6 */2 * * * $HOME/bin/build_farm.sh` .... but there was a big problem ...
 20. My cronjob ran great for a couple weeks.  Then another problem popped up running the cron job in that the test portion suddenly started failing with an odd error:
 <pre><code>** runtest error: Failed to open /dev/tty: No such device or address</code></pre>
-This is not a sudo issue.  This is happening because the cron daemon does not give a tty to the cronjob that it starts.  (How the heck did it ever work?)  The runtest script needs a tty in normal operation.  To fix this, I used an old trick of ssh'ing to localhost with the *-tt* option to **force** allocation of a local tty when starting the *build_farm.sh* script.  To do this, you need to configure the **farm** user to use key-based authentication with its own key.  Assuming you have not generated an ssh key yet:
+This is not a sudo issue.  This is happening because the cron daemon does not give a tty to the cronjob that it starts.  (How the heck did it ever work?)  The runtest script needs a tty in normal operation.  To fix this, you have two options: a) scripting magic to start screen and run the build inside of screen  b) an old trick of ssh'ing to localhost with the *-tt* option to force allocation of a local tty when starting the *build_farm.sh* script.
+<pre></pre>
+**Option A**: To use the screen based solution, I made a simple script:
+<pre><code>
+$ more $HOME/bin/build_farm_screen.sh
+#!/bin/bash
+TITLE="BuildFarm"
+COUNT=`screen -list | grep $TITLE | wc -l`
+if [ $COUNT -eq 0 ]; then
+  echo "Screen not running, start a new one"
+  screen -d -m -S $TITLE
+fi
+screen -S $TITLE -p 0 -X stuff 'for DACONF in $HOME/code/build-farm.conf
+  do
+    $HOME/bin/build_farm.sh --config=$DACONF $@ 2>/dev/null
+  done
+'
+</code></pre>
+Note that the lone single quote on the last line is required, and it must be on the next line, not at the end of the previous line because it emits a newline, causing the command to be executed in the screen session.  Once that works properly, then the cron command changes to:
+<pre>`6 */2 * * * $HOME/bin/build_farm_screen.sh`</pre>
+**Option B**: To use the ssh based solution, you need to configure the **farm** user to use key-based authentication with its own key.  Assuming you have not generated an ssh key yet:
 <pre><code># Press Enter to use defaults for all questions in
 # next command, including no password
 ssh-keygen -t dsa
@@ -53,7 +73,7 @@ cat .ssh/id_dsa.pub >> .ssh/authorized_keys
 # Do the following command once to accept the new host key
 ssh farm@localhost</code></pre>
 Once that works properly, then the cron command changes to:
-<pre><code>6 * * * * ssh -tt farm@localhost $HOME/bin/build_farm.sh</code></pre>
+<pre>`6 */2 * * * ssh -tt farm@localhost $HOME/bin/build_farm.sh`</pre>
 21. The default tests that are run are a limited set, from 1 to 999.  This covers basic Exim functions, but does not exercise a lot of the advanced functions.  Once a few cronjob runs complete successfully, increase the range of tests to run.  Edit the *build-farm.conf* file and change the `range_num_tests => '1 999',` to `range_num_tests => '1 5999',` and it will run more advanced tests.