controller/README: reworked from top-srcdir README

* README: Made as symlink to controller/README.
* controller/Makefile.am: Distribute the README and configuration
file template.
* controller/README: Reworked version of README following current
API.
* controller/doc/dtf-controller/OSID.sh.template: New
configuration template.
* tester/dtf-prepare-testsuite: Prepare also basic taskdir
structure.

5 files changed, 155 insertions, 57 deletions

diff --git a/README b/README
index de16e14..6f1e091 100644..120000
--- a/README
+++ b/README
@@ -1,56 +1 @@
-GENERAL INFO
-============
-
-System checking (dummy) testsuite fw.  The tests are *expected* to be
-destructive and always performed under root account; test writer should only
-make sure that no test conflicts with others (so that all tests are able to run
-on one machine successfully in any order).
-
-TODO: bash-only, unix..
-
-OVERVIEW
-========
-
-
-Each file should consist of config.sh and runtest.sh.  Both are supposed to be
-"sourced" into another scripts (so no need to have execute permissions).  Each
-test case should have its own directory.
-
-USAGE (locally)
-===============
-
-The most simple usage is like `./run`.  Script is able to search for available
-test-cases and then run them on local machine.  Note that this is not generaly
-safe and you should avoid that in most cases.  For more info, run
-`./run --help`.  TODO: The testsuite is root-only.
-
-REMOTE RUN
-==========
-
-You need to have OpenStack credentials file in ./private/ostack.yml configured.
-The file should look like (be sure that only you can read that file):
-    $ cat ./private/ostack.yml:
-    ---
-    os_username: os1username
-    os_tenant_id: 9df30fc192f5xxxxxxxxxxxxxxxx0110
-    os_nova_password: your_os_password
-
-Then it should be enough to run:
-
-    $ ./run_remote
-
-API for config.sh file
-======================
-
-Variables which should/may be defined in config.sh file.
-
-$DTF_TEST_ID - unique ID of task.  Without spaces.
-
-$DTF_TEST_DESCRIPTION - descriptive info about test, will be used for
-generating html or otherwise formated result output.
-
-REQUIREMENTS
-============
-
-Packages needed to successful run
-    * ansible (remote running)
+controller/README
\ No newline at end of file
diff --git a/controller/Makefile.am b/controller/Makefile.am
index 0df88b8..e271af9 100644
--- a/controller/Makefile.am
+++ b/controller/Makefile.am
@@ -6,6 +6,9 @@ bin_SCRIPTS = \
 	bin/dtf-return-machine \
 	bin/dtf-controller
 
+doc_DATA = README \
+	   doc/dtf-controller/OSID.sh.template
+
 sysconf_DATA = etc/dtf.sh
 
 pkgdata_DATA = $(srcdir)/share/dtf-controller/parse_credsfile
@@ -89,7 +92,8 @@ CONTROLLERDATA = \
 EXTRA_DIST = \
 	    $(CONTROLLERSOURCES) \
 	    $(CONTROLLERDATA) \
-	    $(srcdir)/libexec/dtf-wait-for-ssh
+	    $(srcdir)/libexec/dtf-wait-for-ssh \
+	    $(srcdir)/doc/dtf-controller/OSID.sh.template
 
 CLEANFILES = $(GENERATED_FILES) .dep $(TEST_GEN_FILES_LIST)
 
diff --git a/controller/README b/controller/README
new file mode 100644
index 0000000..136c476
--- /dev/null
+++ b/controller/README
@@ -0,0 +1,118 @@
+Dummy (or Destructive) Testsuite Framework (DTF)
+================================================
+
+Testsuite supported by this framework is expected¹ to be destructive, may
+require root permissions or basically whatever.  So do not run such testsuite on
+your machine unless you *really* know what you are doing.  It is always better
+to create temporary virtual machine to run them there (we have some tooling for
+OpenStack VM provisioning).
+
+
+WORK-FLOW
+---------
+
+In general, we expect these steps for running the testsuite:
+
+    * generate self-standing testsuite tarball
+    * start (temporary) virtual machine
+    * copy the test tarball on the new machine and perform testing
+    * collect the results from VM
+    * terminate the VM
+
+However, the testsuite is designed so it may be developed (and thus run)
+locally.
+
+OVERVIEW
+--------
+
+The framework consists of basically two parts, 'tester' and 'controller'.
+
+The 'tester' component is something like tool-set to help users with writing
+theirs 'testsuites'.  That is (a) convenient (Bash) library available for
+for testsuite, (b) main running script (named 'run', it is also part of DTF API)
+and (c) tooling which helps with testsuite initialization.
+
+The 'controller' part is tool-set which helps you to automatize running of the
+testsuite on remote boxes (currently on OpenStack VMs only).
+
+
+PORTABILITY
+-----------
+
+Currently, the tools here are mostly written in Bash (not shell) and Perl and
+thats the reason why you need² to have these languages working on your system.
+Also, it was tested only on GNU/Linux operating system.
+
+
+CREATE TESTSUITE
+----------------
+
+Each testsuite must be self-standing, distributable and ideally non-destructive.
+Creating testsuite should follow this cook-book:
+
+* Create the directory structure:
+
+            $ mkdir YOURPKG_TEST_DIR
+            $ dtf-prepare-testsuite YOURPKG_TEST_DIR
+
+  Then prepares the 'dtflib', 'run' script and basic dummy task for you.  The
+  dummy test-case created is in 'YOURPKG_TEST_DIR/tasks/sample/runtest.sh'.
+
+  Be aware of the fact that 'dtf-prepare-testsuite' is expected to be always run
+  against latest GIT version of that script.  The 'dtflib' and 'run' files (and
+  probably other) will then be copied from GIT.
+
+* Test the sample:
+
+            $ ./YOURPKG_TEST_DIR/run
+            RUN dummy-sample ...                    [  OK  ]
+
+  The 'runtest.sh' file must have the 'run()' function defined and should follow
+  the exit-status API defined in 'run' script.
+
+* To distribute the tarball, just run:
+
+            $ ./YOURPKG_TEST_DIR/run --dist | gzip > testsuite.tar.gz
+
+  Also, please look at the `YOURPKG_TEST_DIR/run --help` output.
+
+
+REMOTE RUN
+----------
+
+To perform this task easily, we expect you to have access to some OpenStack
+instance.  You need to have OpenStack credentials file in
+'~/.dtf/private/os/OSID.yml' (note the OSID identifier).  The file should look
+like (be sure that only *you* can read that file):
+
+    $ cat ~/.dtf/private/os/OSID.yml
+    ---
+    os_auth_url: http://control.example.com:5000/v2.0
+    os_tenant_id: 9df30fc192f5xxxxxxxxxxxxxxxx0110
+    os_tenant_name: Your OS Project
+    os_username: os1username
+    os_nova_password: your_os_password
+
+Also, you must have your distribution images prepared available in OpenStack.
+This needs to be configured for DTF in '~/.dtf/os/OSID.sh'.  See the
+'OSID.sh.template' doc file for example configuration.
+
+Then it should be enough to run:
+
+    $ dtf-run-remote --distro=fedora --distro-version=20 --taskdir YOUR_TEST_DIR
+    ...
+
+
+REQUIREMENTS
+------------
+
+Packages needed to successful run
+    * ansible (for remote runs)
+    * Perl
+    * Bash
+    * perl(Text::Xslate)
+    * perl(YAML::Syck)
+
+----
+¹ However, making tests it non-destructive is highly recommended.
+² More portable approach was still not needed.
diff --git a/controller/doc/dtf-controller/OSID.sh.template b/controller/doc/dtf-controller/OSID.sh.template
new file mode 100644
index 0000000..e37909d
--- /dev/null
+++ b/controller/doc/dtf-controller/OSID.sh.template
@@ -0,0 +1,20 @@
+declare -A os_flavor_ids os_image_ids
+
+export os_flavor_ids=[]
+export os_image_ids=[]
+
+os_flavor_ids["fedora19"]="a4827976-e727-4135-ba59-7d5fdb9ce4e2"
+os_image_ids["fedora19"]="8ef96554-5f93-4cae-8c4f-225c6239eb49"
+
+os_flavor_ids["fedora20"]="a4827976-e727-4135-ba59-7d5fdb9ce4e2"
+os_image_ids["fedora20"]="5fd723b7-e00d-49d3-b17b-65af842d02ab"
+
+os_flavor_ids["fedora21"]="a4827976-e727-4135-ba59-7d5fdb9ce4e2"
+os_image_ids["fedora21"]="27358d7b-7c31-444b-8d92-6f3bc81777e0"
+
+os_flavor_ids["fedorarawhide"]="a4827976-e727-4135-ba59-7d5fdb9ce4e2"
+os_image_ids["fedorarawhide"]="cc98b503-d849-48bc-8541-b1a903b1f564"
+
+export os_keypair=your-keypair-id
+export os_security_group=your-sec-group-id
+export os_network_dev=os-project-network-id
diff --git a/tester/dtf-prepare-testsuite b/tester/dtf-prepare-testsuite
index 76031a9..0e1c54c 100755
--- a/tester/dtf-prepare-testsuite
+++ b/tester/dtf-prepare-testsuite
@@ -6,3 +6,14 @@ srcdir=$(cd -P -- "$(dirname -- "$0")" && pwd -P) || exit 1
 
 ln -sf "$srcdir/run" "$tasks_srcdir"
 ln -sf "$srcdir/libdtf" "$tasks_srcdir"
+mkdir -p "$tasks_srcdir/tasks/sample"
+
+cat <<EOF > "$tasks_srcdir/tasks/sample/runtest.sh"
+export DTF_TEST_ID="dummy-sample"
+export DTF_TEST_DESCRIPTION="Just an example."
+
+run()
+{
+    return 0
+}
+EOF