Skip to content

Rework of Package Builder documentation #1216

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Draft
wants to merge 1 commit into
base: master
Choose a base branch
from
Draft

Rework of Package Builder documentation #1216

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
183 changes: 25 additions & 158 deletions src/content/docs/en-us/features/package-builder.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -8,163 +8,36 @@ import Callout from '@choco-astro/components/Callout.astro';
import Iframe from '@choco-astro/components/Iframe.astro';
import Xref from '@components/Xref.astro';

> Chocolatey's Package Builder allows you to create fully ready to go software deployments for Windows in 5-10 seconds! There is nothing faster than Chocolatey when it comes to preparing software for an unattended deployment across your organization.
<div class="card card-body card-border-top pt-c2">
<center>
<p class="h3">Available In:</p>
<p class="mb-0">
Chocolatey for Business
</p>
</center>
</div>

* Generate packages based on installers and zips
* Generate packages by reflecting over Programs and Features
* Generate packages from the Package Builder UI
## Summary

Creating packages is a pretty quick process as compared to manually installing software on multiple machines. There is still some time involved to create a package. Even the best packagers take between 5-10 minutes to create a package. Chocolatey's Package Builder creates high quality packages in 5-10 seconds when pointed to native installers and zips! You can even point package builder to both a 32-bit and 64-bit url and seconds later you have a fully functioning package using all local/embedded resources!
When you need a package for unattended deployment across your organization, there's nothing faster than **Package Builder**.

Chocolatey for Business is able to inspect an installer and determine silent arguments and complete packaging components for you, saving you hours of time in packaging and maintaining software!
Let Package Builder do the heavy lifting and create packages ready for deployments in as little as 5-10 seconds!

## Usage
Package Builder can:
- Generate packages based on installers and zips from local _and_ remote locations using 32-bit or 64-bit URLs, or both at the same time
- Automatically detect silent arguments, removing the need to use third-party investigation tools
- Work with automation to update a package when a new version of the software inside is released, eliminating the need for manual package updates
- Work with <Xref title="Package Templates" value="create-custom-package-templates"/> to increase ease-of-use and provide simplicity to a complex process

### Command Line

When calling `choco new`, just add `--file=value` to point to a native installer and Chocolatey for Business will automatically determine the silent arguments, create the packaging and wrap that all around the installer.

![Create Packages from Installers - if you are on https://docs.chocolatey.org/en-us/features/package-builder, see commented html below for detailed description of image](/images/features/features_packages_from_installers.png)

{/*
Text in the image above:

Chocolatey for Business automatically creates all packaging from an installer!

Create Packages for Installers In Seconds

- What used to take minutes or hours, is now done in seconds.
- Allows customization
- Automatically create packages for your entire organization's file share in under 15 minutes, saving you weeks of work.

This image shows running `choco new --file .\installers\1Password-4.6.0.598.exe`.

*/}

### Package Builder UI

Starting in version 1.8.0 of the licensed editions, you have access to the Package Builder UI.

Simply right click on an installer, executable, or zip type and select "Create Chocolatey Package..."

![Package Builder UI](/images/package-builder/package-builder-ui.png)

Then just add in and fill out the requested information. It uses `choco new` under the covers allowing you to really ramp up fast, especially when you don't have a lot of command line experience.

Another way to bring up the ui is to call `packagebuilder` from the command line.
When compared to manually installing software on multiple machines, creating a package for deployment is much more efficient; spending time up front to create
the package means you don't need to manually install or upgrade the software directly on the machine. When combined with <Xref title="Central Management" value="central-management"/>, installing and upgrading your
endpoints becomes virtually effortless.

## See It In Action

### Package Builder CLI and Scripts

We've prepared a short video going over the concepts:

[![Chocolatey's Package Builder - Package Builder CLI and Scripting](/images/package-builder/package-builder-cli-video.png)](https://www.youtube.com/watch?v=6TXY5Ie-3wg&list=PLfn-TaDnc1us5X-PVlxW8M1h-6mXEXZSG&index=1 "Chocolatey's Package Builder - Package Builder CLI and Scripting")

Quickly script out creating packages for your entire organization's cache of software, allowing you to completely automate your Windows installations in moments, not months. You can do that with a simple script:

```powershell
# Path to your installers, will navigate subdirectories
$path = '\\company.file.server\installers'

# Generate packages over supported types of files
$supportedTypes = @('.exe', '.msi', '.7z', '.zip', '.msu', '.msp')
Get-ChildItem -Path $path -Recurse | ?{
$extension = [System.IO.Path]::GetExtension($_.Name)
$supportedTypes.Contains($extension)
} | %{
Write-Host "$($_.FullName)"
# Run choco new against the installer
& choco new --file "$($_.FullName)" --build-package --outputdirectory $pwd
}
```

As you see this script, it is doing the following:
* Taking a path to where installers, zips, etc are located (`$path = '\\company.file.server\installers'`)
* Setting up support types of files to use with Package Builder (`$supportedTypes = @('.exe', '.msi', '.7z', '.zip', '.msu', '.msp')`)
* Looping over all that it finds in that folder and all subdirectories (`Get-ChildItem -Path $path -Recurse`)
* Find files that apply (`$supportedTypes.Contains($extension)`)
* Run choco new, but point it to the full path to the file (`& choco new --file "$($_.FullName)"`), ask it to attempt to build the package (`--build-package`) and have the output in present working directory (` --outputdirectory $pwd`)

### Package Builder UI

Not every person is going to love the command line or may not be familiar with the command line and at Chocolatey we realize this. We've spent countless hours talking to customers and with their feedback we're introducing Package Builder UI. This also gives you an opportunity to transition from existing UI tools while taking advantage of powerful Chocolatey concepts!

We've prepared a short video to show the power of the UI:
[![Chocolatey's Package Builder - Package Builder UI](/images/package-builder/package-builder-ui-video.png)](https://www.youtube.com/watch?v=qJNKR_PEQqY&list=PLfn-TaDnc1us5X-PVlxW8M1h-6mXEXZSG&index=2 "Chocolatey's Package Builder - Package Builder UI")

### Generate Packages from Programs and Features

Another way Package Builder can generate packages is based on looking at what is installed on a system in Programs and Features. This gives you lightning quick ramp up time in both package and automating your Windows software installations!

[![Chocolatey's Package Builder - Generate Packages from Programs and Features Automatically!](/images/package-builder/package-builder-programs-features-video.png)](https://www.youtube.com/watch?v=Mw_ReipnskI&list=PLfn-TaDnc1us5X-PVlxW8M1h-6mXEXZSG&index=3 "Chocolatey's Package Builder - Generate Packages from Programs and Features Automatically!")

<Callout type="info">
To see all feature videos for Chocolatey for Business, please visit https://chocolatey.org/resources/features#c4b.
</Callout>

### More business concepts

![auto package creation/synchronize](/images/gifs/choco_business_features.gif)

## Options and Switches

When running `choco new` in the Business editions, pass the following:

```powershell
--file, --url=VALUE
Inspect a file (native installer, zip, patch/upgrade file, or remote url
to download first) to to completely create a package with proper silent
arguments! Can be 32-bit or 64-bit architecture. Available in Business
editions only.

--file64, --url64=VALUE
Optional - used when specifying both a 32-bit and a 64-bit file. Can be
an installer or a zip, or remote url to download. Available in Business
editions only.

--keepremote, --originallocation, --original-location, --useoriginallocation, --use-original-location, --useoriginalfileslocation, --use-original-files-location
Use Original Files Location - when using file or url, use the original
location in packaging. Available in Business editions only.

--checksum, --downloadchecksum, --download-checksum=VALUE
Download Checksum - checksum to verify File/Url with. Defaults to empty.
Available in Business editions only.

--checksum64, --checksumx64, --downloadchecksumx64, --download-checksum-x64=VALUE
Download Checksum 64-bit - checksum to verify File64/Url64 with.
Defaults to empty. Available in Business editions only.

--checksumtype, --checksum-type, --downloadchecksumtype, --download-checksum-type=VALUE
Download Checksum Type - checksum type for File/Url (and optional
separate 64-bit files when specifying both). Used in conjunction with
Download Checksum and Download Checksum 64-bit. Available values are
'md5', 'sha1', 'sha256' or 'sha512'. Defaults to 'sha256'. Available in
Business editions only.

--pauseonerror, --pause-on-error
Pause on Error - Pause when there is an error with creating the package.
Available in Business editions only.

--buildpackage, --build-package
Build Package - Attempt to compile the package after creating it.
Available in Business editions only.
```
Package Builder can be used two ways: directly from the command line or through an interactive user interface. The short video below demonstrates both to detail its user flexibility!

## FAQ

### How do I take advantage of Package Builder?

You must have a [Business edition of Chocolatey](https://chocolatey.org/compare). Business editions are great for organizations that need to manage the total software lifecycle.

### I'm a licensed customer, now what?

When you run `choco new`, you can add `--file` and point Chocolatey at the installer file and let Chocolatey figure out everything for creating a package and the silent arguments and wrap that around the installer.

### Will this become available for lower editions of Chocolatey?

Package Builder will only be available in C4B (Chocolatey for Business).

### How does it work?

It inspects the installer file using a series of rules that helps determine the installer type. From there it builds a package with the information it is able to extract from the installer.
Expand All @@ -179,26 +52,20 @@ It is able to detect 12 types of installers currently.

### Does it always find the silent uninstall arguments?

In over 70% of the cases it will, but not always. Even with this in mind, it still removes 90% of the packaging work. When it can't create a fully unattended softare deployment, it will create a TODO file for you to complete. See the next question on how to handle cases where it can not.
In over 70% of the cases it will, but not always. Even with this in mind, it still removes 90% of the packaging work. When it can't create a fully unattended software deployment, it will create a TODO file for you to complete. See the next question on how to handle cases where it cannot.

### This was unable to detect custom installer arguments.

Unfortunately, some installers out there are just a pain to work with. In the case of custom installers, you may be able to find the silent arguments for install and uninstall by searching online. If you can not find anything, consider unpacking the installer and putting the software binaries directly in the package.
Unfortunately, some installers out there are just a pain to work with. In the case of custom installers, you may be able to find the silent arguments for install and uninstall by searching online. If you cannot find anything, consider unpacking the installer and putting the software binaries directly in the package.

### Does it create auto unattend files?
### Does it create automatic unattended files?

Unfortunately, it is not able to do this. See the <Xref title="automatic internalize and recompile packages feature" value="automate-package-internalization" /> to take advantage of thousands of existing packages without a need for internet access.
Unfortunately not. See the <Xref title="automatic internalize and recompile packages feature" value="automate-package-internalization" /> to take advantage of thousands of existing packages without a need for internet access.

### Does it work with zip archive?

Yes, but somewhat naively. It will generate the packaging to unpack the archive for both 7z and zip files.
Yes, although somewhat naively. It will generate the packaging to unpack the archive for both 7z and zip files.

### Does this work with keeping the installer on a UNC share or elsewhere yet?

Yes, as of Licensed version v1.6.0+. Use `--use-original-location`.

## Common Issues and Resolutions

### I get "Name is required. Please pass in a name for the new package."

This occurs when you are not running Chocolatey for Business or don't have your client properly licensed. Please see <Xref title="licensed installation" value="setup-licensed" /> for more details.