Anatomy of a Chocolatey Package

In this article, I will dive into a Chocolatey package to show the important components.

When utilizing a technology, sometimes thinking of it as a “black box” is good enough. Other times IT professionals are more curious to know exactly how a technology works and what is happening in the background.

Chocolatey is one of those magic tools that does a lot to automate the way you manage software. You can certainly use it without knowing anything about what is happening behind the scenes or even what a package actually is.

Let’s Unzip

Chocolatey uses NuGet technology to package software. A package has a .nupkg extension, but technically is just a zip file renamed to that extension.

Related: Chocolatey Is Quite Yummy

To download a Chocolatey package to see what is inside, we can use choco download:

C:\temp> choco download urbackup-client

The package I will use as an example is called UrBackup. It’s a free and open-source backup software that I actually maintain on the Chocolatey community repository. After using Chocolatey to download the package, it expands the important files into a folder for us to look at.

C:.

└───urbackup-client

    │   urbackup-client.nuspec

    │

    └───tools

        │   chocolateyinstall.ps1

        │

        └───files

                UrBackup Client NoTray 2.2.6.exe

                UrBackup Client NoTray 2.2.6.exe.ignore

The first file we will look at is the .nuspec. This is an XML formatted file that holds metadata about the package. Information such as the package name, version, author, project URL, and description can be contained here.

C:\temp\download\urbackup-client> cat .\urbackup-client.nuspec

<?xml version="1.0"?>

<package xmlns="http://schemas.microsoft.com/packaging/2010/07/nuspec.xsd">

  <metadata>

    <id>urbackup-client</id>

    <version>2.2.6</version>

    <title>UrBackup-Client (Install)</title>

    <authors>Martin Raiber</authors>

    <owners>Martin Raiber</owners>

    <projectUrl>http://www.urbackup.org/</projectUrl>

    <requireLicenseAcceptance>false</requireLicenseAcceptance>

    <description>UrBackup is an easy to setup Open Source client/server 
backup system, that through a combination of image and file backups 
accomplishes both data safety and a fast restoration time.

File and image backups are made while the system is running without 
interrupting current processes.

UrBackup also continuously watches folders you want backed up in order to 
quickly find differences to previous backups. Because of that, incremental 
file backups are really fast.

Your files can be restored through the web interface, via the client or 
the Windows Explorer while the backups of drive volumes can be restored 
with a bootable CD or USB-Stick (bare metal restore).

A web interface makes setting up your own backup server really easy. 
For a quick impression please look at the screenshots here.

Currently there are over 8300 running UrBackup server instances (with 
auto-update enabled) with some instances having hundreds of active 
clients.</description>

    <tags>urbackup-client admin backup</tags>

  </metadata>

</package>

Another piece of information you may find here with certain packages is its dependencies. These packages need to be installed prior to installing the package itself.

Installation Script

If we dive into the “tools” folder we find a PowerShell script called ChocolateyInstall. This is where the PowerShell install magic happens. Depending on the type of installer (MSI, EXE for example) these scripts contain silent installation parameters, the package it is installing and the checksum. Since it is a PowerShell script, this is highly customizable.

C:\temp\download\urbackup-client\tools> cat .\chocolateyinstall.ps1

$ErrorActionPreference = 'Stop';

 

$packageName  = 'urbackup-client'

$toolsDir     = "$(Split-Path -parent $MyInvocation.MyCommand.Definition)"

$fileLocation = ''

 

#Based on Nsis

$packageArgs = @{

  packageName   = $packageName

  softwareName  = 'urbackup-client*'

  fileType      = 'exe'

  silentArgs    = "/S"

  validExitCodes= @(0)

  url           = "$(Split-Path -parent $MyInvocation.MyCommand.Definition)\files\UrBackup Client NoTray 2.2.6.exe"

  checksum      = 'F602561D9F1CDE6035FEFB6D388C885A6DA16AAFCE8F9411E164496A3E3B542E'

  checksumType  = 'sha256'

  url64bit      = ""

  checksum64    = ''

  checksumType64= 'sha256'

  destination   = $toolsDir

  #installDir   = "" # passed when you want to override install directory 
- requires licensed editions 1.9.0+

}

 

Install-ChocolateyPackage @packageArgs

As you can see we are using /S as the silent install option and pointing the URL parameter to the URL or file location of where to download the urbackup client software (in this case the installer is embedded into the package). One great security feature of Chocolatey is that ensures the checksum stated in this script is the same as the installation file that is downloaded locally.

Installer Files

In order to install a piece of software, you need an installation file, right? Chocolatey, by default, keeps these in a folder called “files”. Here, you will find whatever files are necessary to install the software, although; as I stated previously dependencies may not be here as it’s best practice to keep them as a completely separate package.

C:\temp\download\urbackup-client\tools\files> dir

 

Directory: C:\temp\download\urbackup-client\tools\files

 

Mode                LastWriteTime         Length Name

----                -------------         ------ ----

-a----        8/20/2018   8:42 AM       30440232 UrBackup Client NoTray 2.2.6.exe

-a----        8/20/2018   8:42 AM              3 UrBackup Client NoTray 2.2.6.exe.ignore

Conclusion

While there are many complex Chocolatey packages in the wild, this should help you understand a very simple package and the important components that make it up. Chocolatey is mostly a combination of NuGet and PowerShell that enables IT professionals to automate software management on Windows.