Chocolatey Software Blog | Boxing The Third Major Release Of

Boxstarter version 3.0 marks the beginning of a new era of Boxstarter and Chocolatey.

Until version 3.0, Boxstarter has been using an old version of chocolatey.dll that could not be updated and caused a series of bugs which are long gone in current Chocolatey CLI releases. Version 3.0 aims to deliver the features you love about Boxstarter, backed by a new mechanism, at it’s core, to allow usage of arbitrary versions of ‘native’ Chocolatey CLI allowing the old version of chocolatey.dll to be gone!

What Is Boxstarter?

Boxstarter was created by Matt Wrock in 2012 and transitioned to Chocolatey Software, Inc. in 2018.

Think of it as a set of PowerShell modules and utilities that wrap around Chocolatey CLI to enable you to solve problems you’d otherwise tackle with products such as Chef, Puppet, Ansible etc.

Boxstarter enables repeatable, reboot resilient Windows environment installations made easy using Chocolatey packages. When it’s time to repave either bare metal or virtualized instances, locally or on a remote machine, Boxstarter can automate both trivial and highly complex installations. Compatible with all Windows versions from Windows 7/2008 R2 forward.

The Problem with Boxstarter v2

All Boxstarter releases prior to version 3.0 used a mechanism to ‘monkey patch’ the internal PowerShell session Chocolatey CLI uses to run it’s install/uninstall scripts in.

Due to the nature of this mechanism, certain extensions (such as the Chocolatey Licensed Extension) could not be loaded and the user would be faced with warnings or error messages at runtime:

Error when registering components for 'chocolatey.licensed.infrastructure...

This trick of injecting Boxstarter magic into Chocolatey CLI stopped working with version 0.9.9 which forced Boxstarter to stick with version 0.9.8.

As a consequence, Boxstarter used chocolatey.dll version 0.9.8 for all Chocolatey CLI commands that ran through Boxstarter, ignoring what the latest available (or already installed) version was.

What Changed in Boxstarter v3.0

The core logic that calls choco <command> from its helper functions changed from the ‘monkey patch’ variant to an all-new extension-based approach.

In the new release, Boxstarter will actively look for choco.exe in $env:ChocolateyInstall and utilize that instead of the bundled chocolatey.dll.
Because of this change, each call to Chocolatey CLI will run in its own PowerShell session, fixing a couple of nasty bugs that were caused by the re-use of the initial session the Boxstarter.Chocolatey module was imported to.
Boxstarter now comes with the package version of Chocolatey CLI and will install this version if it is not already installed on the target computer.

Besides the changes in Boxstarter itself, a lot of organizational changes happened in the background.

The CI/CD process was improved and releases should be quicker and easier to follow.

Best Features Of Boxstarter

Reboot Resiliency

This is probably the most widely known feature of Boxstarter.

Open BoxstarterShell, use Install-BoxstarterPackage and pass -Credentials.
If the system requires a reboot during/after installation, it will automagically reboot and continue where it left off.

There may even be multiple reboots in a deeply nested dependency chain or explicitly when done via a Boxstarter script.

Install-BoxstarterPackage <PACKAGENAME> -Credential (Get-Credential)

Remote Installations

Take your automation skills to the next level and install packages remotely!

Install-BoxstarterPackage takes a ComputerName parameter.
You can also pass credentials for multiple hosts! Needless to say it’s easiest if the user of the current PowerShell session has WinRM permissions on the remote host.

$myHosts = @('devtest-1', 'devtest-42')
$packages = @('firefox', 'vscode')

$myHosts | ForEach-Object 
  Write-Host "please provide credentials for '$_'"
  @
    ComputerName = $_
    Credential   = Get-Credential
  
 | ForEach-Object 
  Install-BoxstarterPackage -PackageName $packages -ComputerName $_.ComputerName -Credential $_.Credential

Creating Advanced Boxstarter Scripts

Every package you want to install requires to be packaged and may have dependencies, install and uninstall scripts, etc.
That’s great, but with Boxstarter, everything can be a package (ok, to be fair, everything can be a chocolateyInstall.ps1)!

The primary use case is to create a simple PowerShell script that utilizes both Chocolatey CLI and Boxstarter commands.
(i.e. from the Boxstarter WinConfig module.)

Now point Install-BoxstarterPackage towards that file (it even can be a URL/gist raw link πŸ˜‰).
And to gain reboot-resiliency superpowers, add the -Credential parameter.

<#
call this script via BoxstarterShell:
$cred=Get-Credential domain\username
Install-BoxstarterPackage -PackageName <path-to-script>.ps1 -Credential $cred
#>

# NuGet package provider. Do this early as reboots are required
if (-not (Get-PackageProvider -Name NuGet -ErrorAction SilentlyContinue)) 
    Write-Host "Install-PackageProvider"
    Install-PackageProvider -Name NuGet -MinimumVersion 2.8.5.201 -Force -Scope AllUsers -Confirm:$False

    # Exit equivalent
    Invoke-Reboot


# Windows features
choco install TelnetClient -source windowsfeatures
choco install Microsoft-Windows-Subsystem-Linux -source windowsfeatures

# Remove unwanted Store apps
Get-AppxPackage Facebook.Facebook | Remove-AppxPackage -ErrorAction SilentlyContinue
Get-AppxPackage Microsoft.MinecraftUWP | Remove-AppxPackage -ErrorAction SilentlyContinue
Get-AppxPackage Microsoft.MicrosoftSolitaireCollection | Remove-AppxPackage -ErrorAction SilentlyContinue
Get-AppxPackage -AllUser -Name Microsoft.Office.Word | Remove-AppxPackage -ErrorAction SilentlyContinue
Get-AppxPackage -AllUser -Name Microsoft.Office.PowerPoint | Remove-AppxPackage -ErrorAction SilentlyContinue
Get-AppxPackage -AllUser -Name Microsoft.Office.Excel | Remove-AppxPackage -ErrorAction SilentlyContinue
Get-AppxPackage -AllUser -Name Microsoft.MicrosoftOfficeHub | Remove-AppxPackage -ErrorAction SilentlyContinue
Get-AppxPackage -AllUser -Name DellInc.PartnerPromo | Remove-AppxPackage -ErrorAction SilentlyContinue
Get-AppxPackage -AllUser -Name Microsoft.Office.OneNote | Remove-AppxPackage -ErrorAction SilentlyContinue
Get-AppxPackage -AllUser -Name Microsoft.MicrosoftSolitaireCollection | Remove-AppxPackage -ErrorAction SilentlyContinue
Get-AppxPackage -AllUser -Name Microsoft.SkypeApp | Remove-AppxPackage -ErrorAction SilentlyContinue
Get-AppxPackage -AllUser -Name Microsoft.YourPhone | Remove-AppxPackage -ErrorAction SilentlyContinue
Get-AppxPackage -AllUser -Name *XBox* | Remove-AppxPackage -ErrorAction SilentlyContinue

# additional software everyone needs
choco install firefox
choco install 7zip
choco install git
choco install vscode

# because we use PowerShell a lot!
Update-Help -ErrorAction SilentlyContinue

# some winconfig
Update-ExecutionPolicy RemoteSigned
Set-WindowsExplorerOptions -EnableShowFileExtensions -EnableExpandToOpenFolder

# install all available win updates
Install-WindowsUpdate -AcceptEula -GetUpdatesFromMS

# ensure UAC is enabled (security!)
Enable-UAC

1-Click Installer

In addition to creating advanced Boxstarter scripts, it’s possible to create clickable URLs that enable you to get going with a given installation script without the need to download and install Chocolatey CLI or Boxstarter itself first.

See Microsoft’s Windows Dev Box Setup examples.

You can easily create your own 1-Click Bootstrapper links like this http://boxstarter.org/package/url?<link to boxstarter ps1 script>

What’s Next?

There are a couple of things on the agenda of the Boxstarter Team (big thanks to Paul and David for their ongoing support!), yet it is hard to put a timeframe on any of it.

In the long run we’re going to clean up a bunch of code, put some work into PowerShell 7 and move away from Windows PowerShell 2 support in line with Chocolatey CLI.
And the Boxstarter website needs to be updated to add the new features.

A ‘Linux compatible’ version of Boxstarter that can be used in CI/CD environments is something I am very keen on implementing (as soon as above tasks have been dealt with πŸ˜„).

I’m happy to be part of the team that worked on getting Boxstarter back to be aligned with Chocolatey again and very much looking forward to the use-cases that will evolve from here.

Want To Give It a Try?

Install Boxstarter with Chocolatey!

choco install boxstarter

If you want to take the new version 3.0.0 beta for a spin, run:

choco install boxstarter --version 3.0.0-beta-20220427-21 --prerelease

After install, you should find a shortcut to launch “BoxstarterShell” on the Windows desktop and in the Start Menu.

BoxstarterShell is basically a shortcut to open a new PowerShell session and load the required Boxstarter modules that are available after install.
See the Boxstarter documentation for more information and help.