Vagrant¶
Overview¶
Vagrant is a tool which installs and configures virtual development environments. It allows development teams to easily specify and share consistent virtual machine configurations.
The dev tools directory (path ‘’sawtooth-core/tools’‘) of the sawtooth-core repository contains a Vagrant configuration which is specifically tailored to Sawtooth development. A new developer with installed copies of Vagrant and VirtualBox can clone the sawtooth-core repository and have a functional VM which can run validators within a few minutes.
A quick introduction to using dev tools is available as a quickstart in this Developer’s Guide.
Layout of the sawtooth-dev-tools git Repository¶
The dev tools directory is structured as follows:
tools/
bootstrap.d/
guest-files/
plugins/
scripts/
tests/
win-bin/
Vagrantfile
- Vagrantfile
- Vagrantfile is the main configuration file for Vagrant. It is ruby code executed by Vagrant and is executed every ime a vagrant command is executed.
- bootstrap.d
- The bootstrap.d directory contains a set of bash scripts which are executed in order during the provisioning step of ‘vagrant up’. These scripts are always executed.
- guest-files
The guest-files directory contains configuration files which are used by the bootstrap.d scripts.
There is also a local-env.sh script which contains environment specific variables for Sawtooth development, such as PYTHONPATH.
- plugins
- The plugins directory contains bash scripts which can be easily configured to execute during the provisioning step of ‘vagrant up’. These scripts run after bootstrap.d scripts.
- scripts
- This scripts directory contains scripts which are sometimes useful to the developer after provisioning has been completed and the developer has a shell in the virtual machine. For example, there are scripts which help build Ubuntu packages.
- tests
- The tests directory includes tests run within the Vagrant environment. These are in addition to the unit and integration tests found in the tests directory of sawtooth-core and sawtooth-validator.
- win-bin
- The win-bin directory includes scripts for running Sawtooth natively under Windows and is not used in the Vagrant environment.
Layout in the Virtual Machine¶
A convenient feature of Vagrant is the easy sharing of directories between the host machine and the guest virtual machine. By default the Vagrant configuration directory is mounted under /vagrant in the virtual machine.
In the dev tools configuration a /project mount point is also defined which provides access to the Sawtooth repositories.
Configuration Options¶
There is a rudimentary configuration system in place which can impact how the Vagrant environment is provisioned.
The files involved are:
conf-defaults.sh
conf-local.sh
conf-local.sh.example
The conf-local.sh file, which is not checked into the git repository, is the one that should be modified locally. This file can be initialized by copying conf-local.sh.example to conf-local.sh.
The conf-default.sh file defines the defaults for configuration values which are not set.
The valid config values are:
- INSTALL_TYPE
By default, this is set to ‘none’. It can be set to one of:
- none - do not install anything by default
- setup.py - build and install sawtooth-core, sawtooth-validator from the git repositories using ‘python setup.py install’
- deb - build and install sawtooth-core, sawtooth-validator from the git repositories by first creating deb packages and then installing those deb packages.
- START_TXNVALIDATOR
- By default, this is set to ‘no’. If set to ‘yes’, then txnvalidator will be started with upstart or systemd. For this option to work, INSTALL_TYPE must be set to ‘deb’.
- PLUGINS
- By default, set to “build_ubuntu_deps install_ubuntu_deps install_sphinx”. Specify a space-separated list of plugins to run. The plugins are contained in the plugins directory.
The following plugins are available:
- build_ubuntu_deps
- This plugin builds the debian packages for cbor, colorlog, and pybitcointools. They are placed in /project/build/packages/.
- install_latex
- This plugin installs Latex, which is required for building a PDF of the documentation. This is disabled by default because it takes a fairly long time to download.
- install_ubuntu_deps
- This plugin installs the debian packages built by build_ubuntu_deps.
- install_sphinx
- This plugin installs sphinx, which is required for building the sawtooth documentation.