Update README with reference to test.sh

README.md

@@ -6,53 +6,6 @@ This playbook will install
 machines, along with the necessary infrastructure (etcd, logging,
 monitoring and alerting).
 
-# Setup
-
-Before running the playbook against test or production environments,
-you'll need to ensure Ansible is set up properly.
-
-## ansible.cfg
-
-Use *ansible-playbook -i hosts.ini* to control the production
-hosts. But first you're going to need a proper ansible.cfg file. There
-are a few important settings that need to be present:
-
-* since some templates use facts from other hosts, if you ever want to
-  run the playbook on a subset of hosts you're going to need a fact
-  cache
-* preferably install Mitogen and set the *strategy* to
-  *mitogen_linear*
-
-Something like the following should do (change the Mitogen path to
-reflect your own installation):
-
-```
-[defaults]
-nocows = 1
-strategy_plugins = /usr/local/mitogen-0.2.9/ansible_mitogen/plugins/strategy
-strategy = mitogen_linear
-force_handlers = True
-fact_caching = jsonfile
-fact_caching_connection = .fact-cachs
-
-[ssh_connection]
-ssh_args = -C -o ControlMaster=auto -o ControlPersist=120s
-control_path_dir = ~/.ansible/cp
-control_path = %(directory)s/%%h-%%r
-pipelining = True
-```
-
-## ANSIBLE\_VAULT\_PASSWORD\_FILE
-
-Decrypt the ansible-vault passphrase from the secrets storage, and
-write it into a file named *.ansible_vault_pw* in this same directory.
-
-Then
-
-```shell
-$ export ANSIBLE_VAULT_PASSWORD_FILE=.ansible_vault_pw
-```
-
 # Configuration
 
 There are some mandatory configuration variables that need to be set
@@ -100,31 +53,50 @@ in the *monitor* group (for redundancy).
 
 # Testing
 
-To test locally (with Vagrant and Virtualbox):
+This repository contains a script to build dynamic, ephemeral test
+environments using virtual machines, so that different combinations of
+Ansible / autoradio / other packages can be tested before deploying
+them to production.
 
 ```shell
-$ vagrant up
-$ export ANSIBLE_HOST_KEY_CHECKING=False
-$ ansible-playbook -i hosts-vagrant.ini site.yml
+$ test.sh my-test
 ```
 
-This will start a 3-node autoradio cluster, with IPs
-10.236.82.10-12. The cluster will be using autoradio packages from the
-default Debian repository.
-
-## Testing with local autoradio builds
-
-If the *source_repository_path* Ansible variable is defined to point
-at the autoradio source repository, the playbook will install
-locally-built autoradio binaries. This can be very useful to quickly
-test local uncommitted changes:
+The above command will generate an Ansible configuration in the
+*my-test* directory, it will start some VMs, and it will run Ansible
+on them deploying the configuration from this repository.
+
+The test environment can be customized by setting environment
+variables when calling test.sh:
+
+* `DIST`: select the Debian distribution to use (default "buster")
+* `LIBVIRT_USER`, `LIBVIRT_HOST`: use libvirt-over-SSH, needs SSH
+passwordless authentication to be set up.
+* `APT_PROXY`: set to the *host:port* address of apt-cacher-ng. When
+using this directive, ensure that the apt-cacher-ng configuration has
+a permissive PassThroughPattern to allow access to https://
+repositories.
+* `VM`: select the VM manager to use, one of "vagrant" (default) or
+"vmine" (used in CI setups).
+* `VERBOSE`: set to a non-empty value to run ansible-playbook with
+increased verbosity.
+* `AUTORADIO_SRC`: if set, points at a local copy of the autoradio
+source repository which will be compiled and installed instead of
+using the default packages from the autoradio Debian repository.
+
+So, for example, if you have a copy of the *autoradio* source
+repository with some local changes that you want to test, you can use:
 
 ```shell
-$ ansible-playbook -i hosts.ini \
-    -e source_repository_path=$HOME/go/src/git.autistici.org/ale/autoradio \
-    site.yml
+$ AUTORADIO_SRC=/path/to/git.autistici.org/ale/autoradio test.sh my-test
 ```
 
+and the test environment in *my-test* will be set up to build
+autoradio from your local sources.
+
+Check the *hosts.ini* file in the my-test directory to find out the IP
+addresses of the virtual machines (which are randomly generated).
+
 ## Test stream
 
 The *test-source.yml* Ansible playbook can be used to quickly setup a