Describes how to use Boxstarter's Chocolatey module to setup a new
environment with your favorite Chocolatey packages.

Boxstarter's Chocolatey module compliments the Boxstarter Bootstrap
module by augmenting its unattended script execution environment
with Chocolatey goodness making it easy to setup a new box with
Chocolatey packages.

Installing Chocolatey
Boxstarter will check to ensure if Chocolatey is installed. If
Chocolatey is not installed it will install it before running any
Chocolatey commands. Boxstarter will also check to see if the .Net
4.5 Framework is installed before installing Chocolatey since the
.Net 4 runtime is a prerequisite.

Chocolatey Boxstarter Packages
When calling Install-BoxstarterPackage or just Boxstarter, a
Package name must be passed to the command. This is a
special Chocolatey package provided by the user that boxstarter asks
Chocolatey to install and it contains the script that is intended to
install all the applications and settings the user wants setup on the
target machine.

This package script has access to all of the Chocolatey helper
functions as well as all Boxstarter logging, WinConfig and
Bootstrapper commands. See AboutBoxstarterBootstrapper and
AboutBoxstarterLogging for information regarding those comands.

This can also be a script file containing the chocolatey install
script. If the package name provided is a URL or resolves to a file.
Then it is assumed that this contains the chocolatey install
script and a .nupkg file will be created using the script.

Creating Packages
Boxstarter provides some functions to make creation and deployment of
packages easy. Use New-BoxstarterPackage to either create a skeleton
package with a minimal nuspec and ChocolateyInstall.ps1 or to import an
existing package into boxstarter. This will put the package source files
in $($Boxstarter.LocalRepo)\<package name>. To pack these source files
use Invoke-BoxstarterBuild <package name>. You may also pack all
package in your repo with Invoke-BoxstarterBuild -all. If you would like
to make your local repo a network share, use Set-BoxstarterShare.

Consuming Boxstarter Packages
The primary gateway to kicking off a Boxstarter.Chocolatey installation
session is Install-BoxstarterPackage. While you may use this
powershell function, you can also call Boxstarter.bat which takes the
exact same parameters as Invoke-CocolateyBoxstarter. If you installed
Boxstarter.Chocolatey via Chocolatey or the setup.bat installer,
boxstarter.bat is placed in your path. Boxstarter.bat will import the
Boxstarter.Chocolatey module and create a powershell session bypassing
ExecutionPolicy. Boxstarter.bat is ideal for calling Boxstarter
remotely. Simply share the Boxstarter base directory and you can access
it via \\serverName\Boxstarter\Boxstarter.bat.

Package Sources
Install-BoxstarterPackage (or Boxstarter) expects just the name of the
bootstrapping package - just like CINST or Nuget. Boxstarter will search
the following locations in this order:

- $Boxstarter.LocalRepo: This is the local repository that by default is
in the BuildPackages directory in the Boxstarter Base Boxstarter Module
directory ($Boxstarter.BaseDir). You can change the default by using the
Set-BoxstarterConfig function with the -LocalRepo argument.

- The public chocolatey feed at

- Myget: The Boxstarter Community Feed at

The last two remote sources can be configured by editing

Running Boxstarter Remotely
When using the Computername, ConnectionURI or Session parameters of
Install-BoxstarterPackage, Boxstarter will attempt to install the package
the the remote maching it is directed at. Boxstarter will check to ensure
that all necessary client side Powershell Remoting settings are correctly
configured. If they are not, Boxstarter will prompt to confirm whether it
should enable them unless the -Force parameter is used. The -Force
parameter will suppress prompts. As part of this configuration, Boxstarter
will enable CredSSP authentication to ensure that any network connection
that the package may try to establish will pass the users credentials.

Boxstarter will also attempt to enable Powershell remoting on the target
machine if it is not already installed. Boxstarter can only do this if the
WMI firewall ports are open on the target computer. If they are not and
powershell remoting is not enabled on the target machine, the installation
will fail. Users can easily enable powershell remoting manually on the
target machine by opening an administrative powershell console on the remote
computer and then issuing 'Enable-PSRemoting -Force'.

Reboot detection
Perhaps the most compelling feature of Boxstarter is its way to handle
reboots during an involved environment setup package. Especially when
you are running patches, installing services and downloading complex
applications. Boxstarter intercepts all calls to Chocolatey install
commands and checks for pending reboots prior to calling Chocolatey. If
a pending reboot exists, Boxstarter reboots the machine and automatically
logs on with the credentials you provided providing an unattended
installation session. After the Chocolatey package completes, if the
package fails and returns the common MSI reboot needed exit code of
3010, Boxstarter will reboot which will likely cause the package to
succeed on the next run. See aboutboxstarterbootstrapper for more
details about the rebooting logic and how you can disable or manually
invoke them.

Package Authoring Considerations
Boxstarter can run any Chocolatey package and any valid powershell
inside that package. However, there are a few things to consider
that may make a Boxstarter Chocolatey package a better installation

- Boxstarter Chocolatey packages should be repeatable. This is
especially true if you anticipate the need to reboot. When Boxstarter
reboots, it starts running the package from the beginning. So ensure
that there is nothing that would cause the package to break if run

- If you have several Chocolatey packages that you want to install
during the Boxstarter session, it is preferable to call CINST
directly from inside your ChocolateyInstall instead of declaring
them as dependencies. This is because Boxstarter cannot intercept
Chocolatey dependencies so those packages will not have any reboot


about boxstarter logging
about the $boxstarter variable in bootstrapper
about boxstarter logging
about the $boxstarter variable in chocolatey

Last edited Nov 9, 2013 at 4:34 AM by mwrock, version 5