create new tag
, view all tags

TWiki deployment for developers: Part 1 - Installation and configuration

Disclaimer: As far as I know, the procedure described here has been used in my own environment only. These days I try to exploit this for test automation, so there'll likely be no changes in the stuff presented here for some time. Proceed at own risk.


Install the following software:

  • Oracle VirtualBox to run virtual machines. Other virtualization products should work as well, but I haven't tried them yet.
  • Vagrant on the same machine where VirtualBox is running. Vagrant creates virtual machines (and destroy them after use) from plain text config files, by feeding the data into the command line interface of VirtualBox.
  • Ansible to configure the software. In my case I run it on my development machine (a virtual machine itself), which serves as the Ansible control machine. The Ansible control machine must be able to connecto to the VirtualBox host with SSH.
  • And finally, create a directory in a convenient location and extract http://www.twiki.org/p/pub/Codev/AutoTWikiPart1/TWikiDevDeployment.tgz to that directory.
Both Vagrant and Ansible are available as packages for Debian and other Linux distributions, and you can get "recent" versions from their own repositories. Feel encouraged to follow the links to the original documentation of these products!

Other requirements:

  • Each virtual machine needs about 1.5GB of disk space.
  • Your user id on the control machine needs to have a SSH keypair. These are located under ~/.ssh/. The private key (with a name like id_rsa) remains on your machine, the public key (with a name like id_rsa.pub) will be transferred to the virtual machines. Works with RSA, DSA, ECDSA, or ED25519 keys. If you don't have one, run the command ssh-keygen and follow the instructions.

This is a set of powerful tools at our hands, each with a plethora of possibilities (have you had a glance at their docs?). For my own benefit, I intend to keep the interface small. With the current rather limited feature set the interface has three parts:

  1. The inventory to do all configuration stuff (see below),
  2. a few Ansible playbooks,
  3. and the command line parameters given to these playbooks for running (see next page).

Configuration: The inventory file

The inventory is a file used by Ansible to describe the hosts it is going to operate on, and some of their properties. An example is contained in the distribution under the name inventory.example. You must customize this inventory to use the deployment tools, because it describes your local environment which is almost certainly different from mine, and save it under a different name.

You can save your inventory under /etc/ansible/hosts, which is Ansibles default location, or pass the file's location as -i parameter on the command line. If you want to keep it under version control, please keep it separate from the deployment tools repository. On the plus side: This file is rather unlikely to change, unless your local environment changes.

The Ansible inventory is a Wikipedia:INI_file style file. The INI-style sections are groups of hosts and parameters for these hosts. As of today, the inventory example looks like this:

[vagrant_host] -- (1)

ansible_user=haj -- (2)
## These are default values defined elsewhere and might be just fine for you
# vagrant_base=/home/{{ ansible_user}}/vagrant -- (3)
# twiki_net=192.168.56 -- (4)

apt_proxy="" -- (5)
mailhost=mail.someprovider.com -- (6)
WebMasterEmail=Big.Boss@example.com -- (7)


  • (1): Enter the IP address or name of the host where VirtualBox and Vagrant are running. The example here works if you are using the default host-only network of VirtualBox.
  • (2): Enter here your user name on the VM host. You should have pubkey authentication enabled with this host. The user doesn't need to be a privileged user!
  • (3): This is the base directory where all Vagrant "project directories" are created. A project directory contains the Vagrantfile which is created by the toolkit and Vagrant metadata. The default is ~/vagrant for the user you specified before. The user and VirtualBox need to have write permission for this directory.
  • (4): This is the IP subnet used for communication with the virtual machines. The default matches the default host-only network of VirtualBox.
  • (5): Enter here the IP address of your APT proxy. If you intend to use the toolkit, you really should have one in place. For Debian/Ubuntu all you need to do is sudo apt-get apt-cacher-ng.
  • (6): This is the MAILHOST configuration to be used in TWiki's configuration.
    • The implementation is incomplete and only works for mailhosts which don't require authentication. In my own installation, I use my development machine as mailhost, where I've installed exim4 and configured it to listen to the twiki_net network as defined above. This way, I can use 'foo@localhost' mail addresses and get the messages delivered to my local spool which is easily available for local tests. This is also implemented as fallback, if there's no setting in the inventory.
  • (7) WebMasterEmail is the setting with the same name in LocalSite.cfg.
    • If you use the fallback for mailhost, you can also use the fallback for WebMasterEmail which is YourLocalUserId@localhost.

Optionally, you can configure the OpenSSH client on the control machine to avoid checking the SSH keys of the short-lived virtual machines by adding two lines to ~/.ssh/config (or creating the file if it doesn't exist). Otherwise this might bite you when you start a SSH session to a VM.

Host 192.168.56.*
    StrictHostKeyChecking no

Next page: Part 2 - Running the playbooks

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


TopicClassification BrainstormingIdea
TopicSummary Install and configure a VM with TWiki from plain text files


Topic revision: r1 - 2018-01-08 - HaraldJoerg
  • Learn about TWiki  
  • Download TWiki
This site is powered by the TWiki collaboration platform Powered by Perl Hosted by OICcam.com Ideas, requests, problems regarding TWiki? Send feedback. Ask community in the support forum.
Copyright © 1999-2018 by the contributing authors. All material on this collaboration platform is the property of the contributing authors.