Merge pull request chocolatey-community#73 from Windos/reademe-update…

…-server2019

(ENGTASKS-1934) Vagrant Box version management

ReadMe.md

@@ -33,7 +33,7 @@ To get started, ensure you have the following installed:
 
  * Vagrant 2.1+ - linked clones is the huge reason here. You can technically use any version of Vagrant 1.3.5+. But you will get the best performance with 2.1.x.
  * VirtualBox 5.2+
- 
+
 **NOTE:** If you decide to run with version 1.8.1 of Vagrant, you are going to need to set the `VAGRANT_SERVER_URL` environment variable as described in this [forum post](https://groups.google.com/forum/#!msg/vagrant-up/H8C68UTkosU/qz4YUmAgBAAJ), otherwise, you will get an HTTP 404 error when attempting to download the base vagrant box used here.
 
 ## Running Verification Manually
@@ -45,9 +45,9 @@ To get started, ensure you have the following installed:
  1. Ensure setup above is good on your machine.
  1. Fork and Clone this repository
  1. Open a command line (`PowerShell.exe`/`cmd.exe` on Windows, `bash` everywhere else) and navigate to the root folder of the repository.  You know you are in the right place when you do a `dir` or `ls` and `Vagrantfile` is in your path.
-   * No idea if bash on Windows (through Git/CygWin) is supported. If you run into issues, it is better to just use `PowerShell.exe` or `cmd.exe`. Please do not file issues stating it doesn't work.
+     * No idea if bash on Windows (through Git/CygWin) is supported. If you run into issues, it is better to just use `PowerShell.exe` or `cmd.exe`. Please do not file issues stating it doesn't work.
  1. Run `vagrant up` to prepare the machine for testing.
-   * **Note** due to the way that vagrant works, the first time that you run this command, the vagrant box named __chocolatey/test-environment__ needs to be downloaded from the [Vagrant Cloud](https://app.vagrantup.com/chocolatey/boxes/test-environment).  This will take quite a while, and should only be attempted on a reasonably fast connection, that doesn't have any download limit restrictions. Once it has downloaded it will import the box and apply the scripts and configurations to the box as listed inside the `Vagrantfile`.  You can find the downloaded box in the `~/.vagrant.d` or `c:\users\username\.vagrant.d` folder.
+     * **Note** due to the way that vagrant works, the first time that you run this command, the vagrant box named __chocolatey/test-environment__ needs to be downloaded from the [Vagrant Cloud](https://app.vagrantup.com/chocolatey/boxes/test-environment).  This will take quite a while, and should only be attempted on a reasonably fast connection, that doesn't have any download limit restrictions. Once it has downloaded it will import the box and apply the scripts and configurations to the box as listed inside the `Vagrantfile`.  You can find the downloaded box in the `~/.vagrant.d` or `c:\users\username\.vagrant.d` folder.
  1. Now the box is ready for you to start testing against.
  1. Run the following command: `vagrant snapshot save good`.  This takes a snapshot of the VM using the built-in snapshot functionality. This means that after testing packages, the VM can be returned to this known "good" state.
 
@@ -76,6 +76,28 @@ When you are ready to reset to the state just before installing:
 * stop the box with `vagrant suspend`, `vagrant halt`
 * delete the box with `vagrant destroy`
 
+### Upgrading the Testing Environment
+
+When bringing up your testing environment Vagrant may report that the box being used is out of date. You can also manually check to see if a newer box is available using the `vagrant box outdated` command.
+
+To upgrade the vagrant box used by your testing environment:
+
+ 1. Download the new box with `vagrant box update`
+     * **Note** as with the initial setup, this is a large download so please be patient
+ 1. Delete the existing testing environment with `vagrant destroy`
+ 1. Restore the `Vagrantfile` back to it's default, i.e. there should not be any uncommented lines from testing packages
+     * **Note** you may wish to take this opportunity to fetch the latest changes from this repository
+ 1. Run `vagrant up` to prepare the testing environment with the new box
+ 1. Snapshot the updated testing environment with `vagrant snapshot save good`
+
+### Using a Specific Vagrant Box Version
+
+If you don't want to use the latest available Vagrant box, you can select a specific box version or otherwise constrain the valid versions used in your testing environment. To do so, edit the `Vagrantfile` and uncomment the `config.vm.box_version` line.
+
+By default this will set the desired box version to "2.0.0" which is the last Windows Server 2012 R2 version available.
+
+You can adjust this setting to meet your needs, for more information on the options available see the documentation on [Version Constraints](https://developer.hashicorp.com/vagrant/docs/boxes/versioning#version-constraints).
+
 For more information on vagrant commands, see the [Vagrant Docs](http://docs.vagrantup.com/v2/cli/index.html)
 
 ## Differences Between This and Package Verifier Service

Vagrantfile

@@ -12,10 +12,14 @@ end
 
 # http://docs.vagrantup.com/v2/vagrantfile/machine_settings.html
 Vagrant.configure("2") do |config|
-  # This setting will download the atlas box at
-  # https://atlas.hashicorp.com/ferventcoder/boxes/win2012r2-x64-nocm
+  # This setting will download the Vagrant Cloud box at
+  # https://app.vagrantup.com/chocolatey/boxes/test-environment
   config.vm.box = "chocolatey/test-environment"
 
+  # Uncomment the following line to restrict the version of the box to use,
+  # otherwise the latest version available will be used.
+  # config.vm.box_version = "2.0.0"
+
   # http://docs.vagrantup.com/v2/providers/configuration.html
   # http://docs.vagrantup.com/v2/virtualbox/configuration.html
   config.vm.provider :virtualbox do |v, override|