~ salmonella-environment-setup (master) 63d496e81eab0fbb7176e327c17eda853266bcad
commit 63d496e81eab0fbb7176e327c17eda853266bcad
Author: Mario Domenech Goulart <mario@parenteses.org>
AuthorDate: Tue May 4 21:03:46 2021 +0200
Commit: Mario Domenech Goulart <mario@parenteses.org>
CommitDate: Tue May 4 21:07:10 2021 +0200
README: update and add web server setup notes
diff --git a/README b/README
index 6cfe812..e78d019 100644
--- a/README
+++ b/README
@@ -31,22 +31,23 @@ The following CHICKEN tools are required
* henrietta-cache (optional -- only for salmonella-run-publish's
local-mode)
* kill-hanging-children (optional, but enabled by default in
- salmonella/conf/common.scm). kill-hanging-children will
- kill child processes of salmonella that exceed a specified
- run time (1h by default).
+ salmonella/conf/common.scm). kill-hanging-children will kill child
+ processes of salmonella that exceed a specified run time (1h by
+ default).
The following directory layout is assumed by run-salmonella.sh (see
"Initial setup" for more details):
-$HOME/src/salmonella-environment-setup
- Clone of the salmonella-environment-setup repository
-
$HOME/local/chicken-4
- CHICKEN 4 installation directory
+ CHICKEN 4 installation directory (in case CHICKEN 4 tools are used)
$HOME/local/chicken-5
- CHICKEN 5 installation directory
+ CHICKEN 5 installation directory (used by default)
+
+By default CHICKEN 5 tools are going to be used. If you want to use
+CHICKEN 4 tools instead, set the `CHICKEN_TESTS_MAJOR_VERSION'
+environment variable to 4.
The following directory layout will be generated by run-salmonella.sh
@@ -60,78 +61,55 @@ $HOME/salmonella/reports
server.
-== Initial setup
-
-The instructions below apply if you want to test both CHICKEN 4 and
-CHICKEN 5.
-
-=== Install CHICKEN 4 & required eggs
+=== Account conventions for dedicated salmonella machines
-run-salmonella.sh will look for CHICKEN 4 tools in
-$HOME/local/chicken. I usually install CHICKEN setting
-PREFIX=$HOME/local/chicken-<version> and create a symlink
-chicken -> chicken-<version> in $HOME/local (that eases
-updating CHICKEN).
-
-Once CHICKEN 4 is installed, we can use it to install the required
-eggs. At the moment the recommendation is to install eggs from git
-(order is important):
+run-salmonella.sh can be used on regular systems with regular user
+accounts. For dedicated salmonella machines we follow a convention of
+using the following user accounts:
-$ git clone https://github.com/mario-goulart/salmonella
-$ cd salmonella
-$ $HOME/local/chicken/bin/chicken-install
+* chicken: regular user account to run salmonella jobs. This user
+ runs run-salmonella.sh via cron.
-$ git clone https://github.com/mario-goulart/salmonella-html-report
-$ cd salmonella-html-report
-$ $HOME/local/chicken/bin/chicken-install
+* awful: in case the salmonella machine serves the salmonella reports
+ and assorted salmonella log files generated by the test jobs, the
+ web server conventionally runs under the awful account, which can be
+ a system account.
-$ git clone https://github.com/mario-goulart/salmonella-diff
-$ cd salmonella-diff
-$ $HOME/local/chicken/bin/chicken-install
-$ git clone https://github.com/mario-goulart/salmonella-feeds
-$ cd salmonella-feeds
-$ $HOME/local/chicken/bin/chicken-install
-
-$ git clone https://github.com/mario-goulart/salmonella-run-publish
-$ cd salmonella-run-publish
-$ $HOME/local/chicken/bin/chicken-install
+== Initial setup
-$ git clone https://github.com/mario-goulart/kill-hanging-children
-$ cd kill-hanging-children
-$ $HOME/local/chicken/bin/chicken-install
+The instructions below apply if you want to run salmonella jobs using
+CHICKEN 5 tools.
=== Install CHICKEN 5 & required eggs
-If you plan to test CHICKEN 5, you'll need CHICKEN 4 and the eggs
-mentioned in the previous section. Additionally, you'll need CHICKEN
-5 and salmonella for CHICKEN 5.
-
run-salmonella.sh will look for CHICKEN 5 tools in
$HOME/local/chicken-5. I usually install CHICKEN setting
PREFIX=$HOME/local/chicken-<version> and create a symlink
chicken-5 -> chicken-<version> in $HOME/local (that eases
updating CHICKEN).
-Once CHICKEN 5 is installed, we can use it to install salmonella for
-CHICKEN 5.
+Once CHICKEN 5 is installed, we can use it to install the required
+eggs. At the moment some eggs are only available in git:
-$ git clone https://github.com/mario-goulart/salmonella salmonella-5
-$ cd salmonella-5
-$ git checkout chicken-5
+$ $HOME/local/chicken-5/bin/chicken-install salmonella-html-report salmonella-diff salmonella-feeds
+
+$ git clone https://github.com/mario-goulart/salmonella-run-publish
+$ cd salmonella-run-publish
$ $HOME/local/chicken-5/bin/chicken-install
+$ git clone https://github.com/mario-goulart/kill-hanging-children
+$ cd kill-hanging-children
+$ $HOME/local/chicken-5/bin/chicken-install
-== Configuring salmonella jobs
-run-salmonella.sh will look for configuration files in the
-salmonella-environment-setup repository, specifically in
-$HOME/src/salmonella-environment-setup/conf
+== Configuring salmonella jobs
-run-salmonella.sh will look for configuration files with .conf suffix
-in that directory. The conf files are Scheme files that usually set
-salmonella-run-publish parameters.
+run-salmonella.sh will look for configuration files (files with a
+`.conf' sufix) in the `conf' directory of the local copy of the
+salmonella-environment-setup repository. The configuration files are
+Scheme files that usually set salmonella-run-publish parameters.
run-salmonella.sh will also read `settings.sh' files from the
configuration directory. These files will be load shell settings
@@ -147,14 +125,68 @@ Where ${OS} is the value returned by (software-version) and ${ARCH} is
the value returned by (machine-type) by CHICKEN.
-
== Running run-salmonella.sh
After you've got everything installed and configured, you can call
run-salmonella.sh with the configuration file names (without
extension) as arguments. Example:
- $HOME/src/salmonella-environment-setup/run-salmonella.sh chicken-4 chicken-5
+$HOME/src/salmonella-environment-setup/run-salmonella.sh chicken-5 chicken-5-clang
+
+This will make run-salmonella.sh pick the chicken-5.conf and
+chicken-5-clang.conf files and shell settings files for ${OS} and
+${ARCH}.
+
+To run those jobs periodically, just configure a crontab entry for the
+run-salmonella.sh command line.
+
+
+== Setting up the web server
+
+Setting up the web server is optional, as it is possible to generate
+reports on a system (which doesn't run the web server) and serve them
+from another system.
+
+The web server is a custom hack to serve salmonella reports out of
+compressed tar files. To install it, run:
+
+$ chicken-install awful-salmonella-tar
+
+The default configuration of the web server in the
+salmonella-environment-setup repository (`awful' directory) assumes
+some conventions:
+
+* The web server runs under the `awful' user account.
+
+* Web server logs go to /var/log/awful (the awful user must be able to
+ write to that directory).
+
+* HTML files extracted from salmonella reports in compressed tar
+ format are cached under /var/cache/awful-salmonella-tar (the awful
+ user must be able to write to that directory).
+
+* Configuration files are conventionally kept at /etc/awful (normally
+ it contains symlinks to actual files in the local copy of the
+ salmonella-environment-setup repository). A typical configuration
+ for the web server can be set up like (assuming
+ salmonella-environment-setup is cloned under
+ $HOME/src/salmonella-environment-setup):
+
+ $ mkdir /etc/awful
+ $ cd /etc/awful
+ $ ln -s $HOME/src/salmonella-environment-setup/awful/awful-salmonella-tar.conf awful.conf
+ $ ln -s $HOME/src/salmonella-environment-setup/awful/privileged.conf
+
+The default configuration expects to serve files from
+/home/chicken/salmonella/reports (that's hardcoded in awful.conf).
+Since web bots can scan salmonella reports and request a lot of files,
+it's recommended to install the robots.txt file in the web server's
+document directory:
+
+$ cd /home/chicken/salmonella/reports
+$ ln -s /home/chicken/src/salmonella-environment-setup/awful/robots.txt
-This will make run-salmonella.sh pick the chicken-4.conf and
-chicken-5.conf files and shell settings files for ${OS} and ${ARCH}.
+How to start and stop the server is system-dependent and not covered
+by this document. The `awful' directory in the
+salmonella-environment-setup repository contains some assorted scripts
+for some systems).
Trap