github.com/alloyci/alloy-runner@v1.0.1-0.20180222164613-925503ccafd6/docs/executors/virtualbox.md (about)

     1  # VirtualBox
     2  
     3  >**Note:**
     4  The Parallels executor works the same as the VirtualBox executor. The
     5  caching feature is currently not supported.
     6  
     7  VirtualBox allows you to use VirtualBox's virtualization to provide a clean
     8  build environment for every build. This executor supports all systems that can
     9  be run on VirtualBox. The only requirement is that the virtual machine exposes
    10  its SSH server and provide a bash-compatible shell.
    11  
    12  ## Overview
    13  
    14  The project's source code is checked out to: `~/builds/<namespace>/<project-name>`.
    15  
    16  Where:
    17  
    18  - `<namespace>` is the namespace where the project is stored on AlloyCI (username, or organization's name)
    19  - `<project-name>` is the name of the project as it is stored on AlloyCI
    20  
    21  To overwrite the `~/builds` directory, specify the `builds_dir` option under
    22  the `[[runners]]` section in
    23  [`config.toml`](../configuration/advanced-configuration.md).
    24  
    25  ## Create a new base virtual machine
    26  
    27  1. Install [VirtualBox](https://www.virtualbox.org) and if running from Windows,
    28     add VirtualBox installation folder (e.g. `C:\Program Files\Oracle\VirtualBox`)
    29     to `PATH` environment variable
    30  1. Import or create a new virtual machine in VirtualBox
    31  1. Log into the new virtual machine
    32  1. If Windows VM, see [Checklist for Windows VMs](#checklist-for-windows-vms)
    33  1. Install the OpenSSH server
    34  1. Install all other dependencies required by your build
    35  1. If you want to upload job artifacts, install `alloy-runner` inside the VM 
    36  1. Log out and shutdown the virtual machine
    37  
    38  It's completely fine to use automation tools like Vagrant to provision the
    39  virtual machine.
    40  
    41  ## Create a new Runner
    42  
    43  1. Install AlloyCI Runner on the host running VirtualBox
    44  1. Register a new AlloyCI Runner with `alloy-runner register`
    45  1. Select the `virtualbox` executor
    46  1. Enter the name of the base virtual machine you created earlier (find it under
    47     the settings of the virtual machine **General > Basic > Name**)
    48  1. Enter the SSH `user` and `password` or path to `identity_file` of the
    49     virtual machine
    50  
    51  ## How it works
    52  
    53  When a new build is started:
    54  
    55  1. A unique name for the virtual machine is generated: `runner-<short-token>-concurrent-<id>`
    56  1. The virtual machine is cloned if it doesn't exist
    57  1. The port forward rules are created to access the SSH server
    58  1. The Runner starts or restores the snapshot of the virtual machine
    59  1. The Runner waits for the SSH server to become accessible
    60  1. The Runner creates a snapshot of the running virtual machine (this is done
    61     to speed up any next builds)
    62  1. The Runner connects to the virtual machine and executes a build
    63  1. If enabled, artifacts upload is done using the `alloy-runner` binary *inside* the virtual machine.
    64  1. The Runner stops or shutdowns the virtual machine
    65  
    66  ## Checklist for Windows VMs
    67  * Install [Cygwin]
    68  * Install sshd and git from Cygwin (do not use *Git For Windows*, you will get lots of path issues!)
    69  * Install Git LFS
    70  * Configure sshd and set it up as a service (see [Cygwin wiki](http://cygwin.wikia.com/wiki/Sshd))
    71  * Create a rule for the Windows Firewall to allow incoming TCP traffic on port 22
    72  * Add the AlloyCI server(s) to `~/.ssh/known_hosts`
    73  * To convert paths between cygwin and windows, use the `cygpath` utility which is documented [here](http://cygwin.wikia.com/wiki/Cygpath_utility)
    74  
    75  [cygwin]: https://cygwin.com/