Machines

minicoin is based on Vagrant, but tries to provide a clearer separation of the data defining machines, and the code implementing the logic.

Machines are defined in the machines section of the minicoin.yml file. The default minicoin.yml file is loaded first. A user-specific minicoin.yml file in ~/minicoin will be loaded if present, and a project specific file in $PWD/.minicoin/minicoin.yml will be loaded last. Those user- and project- specific files and can add additional boxes, and extend or override settings from boxes in the default file.

Machine definition

A machine needs to have a unique name, and a box that vagrant can launch a VM from. All other settings are optional.

The following parameters are available:

Mandatory settings

  - name: [string]            # The name of the machine; will also be set as the hostname
    box: [string]             # The vagrant box for the machine, usually as namespace/boxname

The name of the box needs to be a string with any characters except /, \, and quotation marks.

Vagrant boxes

You can use any functional vagrant box with minicoin. For a list of freely available boxes, see vagrantcloud.com. These are primarily different versions of various linux distributions, perhaps with some software pre-installed to make them suitable for specific tasks. For minicoin, the boxes from the "generic" and "bento" namespaces are good choices, and available for a range of providers.

Private boxes

Boxes might be located at a private location, in which case the box value for the machine needs to be specified as org/$minicoin_key/box, and the environment variable $minicoin_key needs to hold the key, e.g.

machines:
  - name: proprietary
    box: tqtc/$minicoin_key/proprietary_os

$ minicoin_key=password123 minicoin up proprietary

Base boxes (and disk images; see Disk provisioning) will be downloaded from the URLs listed in the urls section of the minicoin.yml file. Servers are attempted in sequence.

urls:
  <org>:
    - server1
    - server2

The servers listed for an <org> key will be used to download boxes for that org, e.g a box tqtc/windows10 will be downloaded from the servers set for org tqtc.

Provisioning

Provisioning steps are defined by listing roles. Some roles can be parameterised by providing a key/value hash.

    roles: [list/hash-list]  # Optional, as per the definitions in the roles subdirectory
      - role1
      - role2
      - role: role3
        key1: value1
        key2: value2

Implicit job parameters

Machines can define multiple settings for how certain jobs should be run on them. The jobconfig can specify which parameters to send to the job, and how job output should be displayed.

If a minicoin run execution matches multiple such configurations, minicoin will present an interactive dialog where the name and description will be displayed.

    jobconfigs:
      - name: [string]        # name of the configuration
        description: [string] # description of the configuration
        job: [string]         # job to which this configuration should apply
        options: [hash]       # will be passed to the job
          key: value          # as "--key value"
          flag:               # as "--flag"
        matchers: [hash-list] # will process lines of job output
          - pattern: [regex]  # matching lines
            color: [string]   # color: red, yellow, green, magenta, cyan, white
            bold: [bool]      # text will be bold if true
            newline: [bool]   # following lines will overwrite this line if true
            replace: [bool]   # guest path will be replaced by host path
            error: [bool]     # output is sent to stderr
            continue: [bool]  # continue with the same format as the previous line
            suppress: [bool]  # suppress the line

If the job defines matchers, then the matchers from the machine will be tried first.

Virtual machine configurations

Those settings are best set in the user's minicoin.yml file, as they depend on the host environment.

    cpus: [int]               # number of CPUs the machine should have
    memory: [int]             # amount of MBs of RAM the machine should have
    vram: [int]               # amount of MBs of video memory the machine should have
    private_net: [string]     # IP address, or "disabled"; use dhcp otherwise
    ports: [hash-list]        # a list of port mappings; see vagrant's attributes
      - id: [string]          # the id of the port mapping
        guest: [number]       # the guest-port
        host: [number]        # the host-port

Display options

    gui:[bool]                # "true" if the VirtualBox gui should be shown
    resolution: [string]      # display resolution, e.g UXGA or WQXGA
    guiscale: [float]         # scale factor for the GUI
    screens: [int]            # number of screens

Expert options for platform/provider specific quirks

    communicator: [string]    # the communicator vagrant should use: ssh, winssh, winrm
    shared_folders: [list]    # set to "disabled" to turn folder sharing off
    os: [string]              # 'windows' or 'mac', overrides auto detection
    provider: [string]        # specify which provider should always be used to run this box

Note: There is only one Vagrantfile which contains the vagrant configuration code, takes care of setting appropriate defaults, works around limitations, and runs the provisioning steps from the machine's definition. You will probably never have to change this file, unless you want to contribute to minicoin.