UPack Documentation

UPack CLI

  • Last Modified: 2018-07-17

The Command-line reference is available on GitHub.

upack.exe is a command-line tool used to create and install universal packages; you can also see which packages are installed on a machine.

Download, Installation, & Source Code

upack.exe is a stand-alone program and does not require installation. Visit the GitHub Releases section to download the latest version.

The source code for upack.exe is hosted on GitHub.

Creating and Publishing a Universal Package with upack.exe

Prerequisites:

Overview

In this tutorial, we will take an existing website and package it into a Universal Package using the upack.exe tool. The files in Accounts.zip are just the build output of a basic .NET web application. For those unfamiliar with .NET, it could just as easily be a Java WAR file, a collection of PHP files, or even static HTML.

Creating a Package

In this step, we will create a Universal Package. The format of the package is simple to understand, and due to a few basic package properties, enables consistent deployment and distribution of the contents within Accounts.zip going forward.

Note: In a typical usage scenario, the "pack" step would be executed by a Continuous Integration server such as TeamCity or Jenkins immediately after build output is generated.

To begin, we will download the Accounts.zip file and extract its contents into a temporary directory (in this example, we will use C:\tmp\accounts). Additionally, we will download upack.exe to a directory already included in the PATH environment variable.

In PowerShell, navigate to C:\tmp\accounts, and enter the following command to package the contents into a Universal Package:

PS C:\tmp\accounts> upack pack . --name=Accounts --version=1.0.0 --title="Accounts Website" --description="This package contains the build output for the Accounts demo website."

This will generate a universal package named Accounts-1.0.0.upack in the same directory.

Pushing a package to a Universal feed in ProGet

Once a package is created, we are now able to publish it to a Universal feed.

Note: In a typical usage scenario, the "push" step would also be executed by a Continuous Integration server sometime after package creation.

Before we can push the package, we must determine the endpoint of the ProGet feed to use it as the push source. After logging into ProGet and browsing to the feed, take note of the endpoint URL:

API Endpoint URL

Using this value, we can now push our newly generated package to the feed using the following PowerShell command:

PS C:\tmp\accounts> upack push Accounts-1.0.0.upack http://progetint/upack/Universe/ --user=Admin:Admin

Naturally, Admin:Admin should be replaced with a valid username/password combination for the specific feed, or omitted entirely to authenticate as the current Windows user or anonymously depending on how ProGet is configured.

Once the package is published to the feed successfully, we can view the package details in ProGet:

Package Details in ProGet

Finding and installing a package to install on a server

Once the package is pushed to ProGet, it can be installed on any server that can access ProGet. In PowerShell, enter the following command to install the latest package contents to an existing directory:

PS C:\tmp\accounts> upack install Accounts --source=http://progetint/upack/Universe/ --target=.\install

This will extract the package contents of the "Universe" feed in ProGet into C:\tmp\accounts\install.

Listing installed packages on a server

Once a package has been installed, upack.exe can query the Universal Package Registry on the local machine for installed packages with the list command:

PS C:\tmp\accounts> upack list

After performing the above steps, this list will contain (at a minimum):

Accounts 1.0.0
From http://progetint/upack/Universe/
Installed to C:\tmp\accounts\install on 2018-04-30T17:01:51.8197700-04:00
Installed by thoven using upack/2.2.0.1

This list is not limited to what is installed by upack.exe, the Universal Package Registry will also contain packages installed from Otter, Hedgehog, BuildMaster, and Romp.

Verifying a downloaded package hash against a Universal feed

There may be cases when we obtain a package from a source other than installing from ProGet directly, or perhaps it was acquired from a different Universal feed (i.e. the package was promoted). In this case, it is useful to verify that the package contents are identical. This can be done by using the verify command:

PS C:\tmp\accounts> upack verify Accounts-1.0.0.upack http://progetint/upack/Universe/ 

The result of this command will either indicate that the hashes match, or issue an error to standard error if they are different.

If you only need to view the hash, you can use the hash command:

PS C:\tmp\accounts> upack hash Accounts-1.0.0.upack

If the exact same pack command was used as described in this tutorial (and we haven’t changed Accounts.zip on our end), the output will be:

0633d10b2223cd9ce94ca70e298c4edb752d6028

Of course, this is a standard SHA1 hash in hexadecimal format, so any existing tools (7zip, sha1sum, etc.) can be used to obtain a package hash. This hash could then be quickly compared to the SHA1 value displayed within ProGet to ensure the package contents are identical.

Repackaging an existing package

When deploying packages, it is common to rewrite package metadata such as version information (e.g. removing pre-release identifiers), adding/appending descriptions, or changing the group name. The repack command can be used for this purpose; it will effectively create a new package with the exact same contents but different metadata. The newly created package will default to any metadata property values of the existing package, and the repack command accepts any property supported by the pack command, or alternatively a upack.json file with values that will be merged into the source package’s upack.json file. Here are some common use-cases for the repack command:

Changing Package Version

PS C:\tmp\accounts> upack repack Accounts-1.0.0-RC007.upack --version=1.0.0

Add metadata elements from a custom upack.json file

PS C:\tmp\accounts> upack repack Accounts-1.0.0.upack --manifest=additional-upack.json --overwrite

additional-upack.json contents:

{
  "description": "This additional metadata will overwrite the package's description, or add one if no description property exists",
  "tags": ["repackaged"]
}

Have a question? Try the Q&A Forum

Our documentation is now Open Source and on GitHub. We highly encourage our users to contribute and get involved! .