TWiki deployment for developers: Part 2 - Running the playbooks

Introduction to playbooks

Ansible playbooks are run with the ansible-playbook command from the directory where the deployment toolkit sits. This command has a full alphabet of options, here's our short version:

ansible-playbook -i your_inventory_file -e var1=value1 -e var2=value2 playbook.yml

Explanation:

• your_inventory_file is the customized inventory from the previous section.
• vari=valuei are key-value pairs of Ansible variables which are used in the playbooks. Each playbook comes with a set of variables which can - or must -be provided on the command line, see the following section. Variables given on the command line have global scope and highest precedence, so you can override any configuration variable or runtime variable, but you shouldn't unless you know what you are doing.

Right now there are just two playbooks: twiki_cgi.yml creates and starts a virtual machine with TWiki 6.0.2 running on Apache2 with the CGI module, without any optional plugins, and twiki_destroy.yml deletes a virtual machine, including its disk files.

I haven't decided yet whether other possible setups (e.g. running on mod_perl or with another login manager) will be implemented as separate playbooks or as additional parameters to the existing playbook.

twiki_cgi.yml - Create a TWiki installation

Minimal use:

• ansible-playbook -i your_inventory_file -e twiki_tgz=/path/to/TWiki.tgz twiki_cgi.yml
  This creates and starts a VM with the following properties:
  • Virtual disks and other VM stuff will be stored under ~/vagrant/twikitest_10/
  • Operating System is Debian Stretch 64bit from https://app.vagrantup.com/debian/boxes/stretch64
  • No package upgrade
  • User vagrant with unlimited sudo permission with your SSH key installed
  • TWiki version as provided in the tgz file
    • "Simple" installation, all stuff is under /opt/twiki
    • LocalSite.cfg with default settings, in particular: TemplateLogin
  • Apache 2 with mod_cgid (i.e. "plain", non-persistent CGI)
    • The Apache configuration has been created using ApacheConfigGenerator
  • TWiki's start URL is http://192.168.56.10/bin/view/Main/WebHome
  • On the first call to configure you need to provide a password
    • I might change this to a default password to make automated config changes using the web interface easier

These parameters can be used:

-i your_inventory: See the previous section.

-e vagrant_box=box/name: This is the name of a box container available from the Vagrant catalog. Right now, the deployment tools work only with boxes which have APT as their package manager. The following boxes have been tested so far:

• debian/jessie64 (with Perl 5.20)
• debian/stretch64 (the default, with Perl 5.24)
• ubuntu/xenial64 (with Perl 5.22)

-e twiki_tgz=/path/to/TWiki.tgz: The path to an archive containing the TWiki distribution.

-e twiki_ip_suffix=<integer 10..99>: This is an "index" for the machine to be created. The default is 10, you need to change it only if you want to run two machines at the same time. The index is used in three places:

• The name of the directory for VM metadata under your configured vagrant_base (see section "The inventory") will be twikitest_ followed by that number. With the default index the directory has the name twikitest_10.
• The IP address where TWiki will use is the twiki_net setting plus the index, so if you use the default values you get the IP address 192.168.56.10. Addresses 192.168.56.100 and above are used by the DHCP server in VirtualBox, so you are safe from collisions if you stay in the range from 10 to 99.
• The name of the TWiki administrator has the number embedded: TWiki 10 Administrator, in case you need to distinguish between mails from different VMs.

-v, -vv, -vvv, -vvvv

Different stages of verbosity.

twiki_destroy.yml - Delete a TWiki installation

This playbook deletes the VM and its virtual disks. In addition, it clears the VM's SSH key from the known_hosts file of the VM host machine and from the control machine. The Vagrant "template" is retained, so the next creation of the same box doesn't need a fresh download of the VM image!

Minimal use:

• ansible-playbook -i your_inventory_file twiki_destroy.yml -e ip_suffix=10
  

These parameters can be used:

-i <your_inventory>

See the previous section on installation and configuration.

-e ip_suffix=<integer 10..99>

The index of the VM to delete. The parameter is intentionally named different as in VM creation and has no default, so it must be provided. This is a safeguard against deleting "the default VM" per accident.

-v, -vv, -vvv, -vvvv

Different stages of verbosity.

-- Contributors: Harald Jörg - 2018-01-08

Discussion