Automatic Packaging for Maintenance

Automatic packaging is a process that package maintainers can run on their own to keep the packages they maintain up to date. It is not a required step for maintaining packages on the community feed (https://chocolatey.org/packages), but it is recommended you find a way to automate the delivery of packages to the community feed when there are updates if you are going to maintain more than 5 packages and you are not the software vendor for the packages you maintain.

NOTE: Not to be confused with the automatic package creation feature in Chocolatey for Business - that feature creates packages directly from software installer files. This feature is for package maintenance of existing packages on the community feed.

Automatic update methods

There are currently two methods that can be used to maintain automatic packages:

Automatic Updater (AU)

You can learn more about the AU updater via its documentation. It is a PowerShell module, so you are doing everything with PowerShell scripts. You can also run everything on AppVeyor so you are not required to schedule updater on your own machine.

Credits

AU is brought to you by a Chocolatey community member Miodrag Milic and it is becoming more awesome all the time.

Requirements

Setup

  1. Fork chocolatey-packages-template and rename it to something like chocolatey-packages (on GitHub - go into Settings, Repository name and rename).
  2. Clone the repo locally.
  3. Head into the setup folder and look for au_setup.ps1. Review that file and then run it.
  4. Follow the README in the setup folder.

When creating packages, you can choose to use --auto or not as AU doesn't use token replacement for updating packages. There are some additional things generated though, so you may want to use the auto switch.

Chocolatey Package Updater aka chocopkgup

http://chocolatey.org/packages/ChocolateyPackageUpdater

The tool that accomplishes this process is known as chocopkgup (Chocolatey Package Updater). It is a free tool (unless you want to use it for uploads to somewhere other than chocolatey.org).

Licensing

Check the license at http://realdimensions.net/licenses/chocolateypackageupdater/license.txt to be sure that it applies to you.

Basically it boils down to this: if you want to use chocopkgup privately, you will need to pay for it. As long as you are publishing to chocolatey.org, the tool is completely free! The license does expire every once in awhile, but if you are keeping up on your chocolatey updates locally, you won't even notice (cup all, remember?).

Credits

This tool makes use of Ketarin. Ketarin is an awesome tool that helps chocopkgup accomplish its tasks.

Requirements

Setup

  1. Fork chocolatey-packages-template and rename it to something like chocolatey-packages (on GitHub - go into Settings, Repository name and rename).
  2. Clone the repo locally.
  3. Install chocopkgup (which will install ketarin and nuget.commandline). choco install chocolateypackageupdater.
  4. Check the config in $env:ChocolateyInstall\lib\ChocolateyPackageUpdater\tools\chocopkgup\chocopkgup.exe.config. The PackagesFolder key should point to where your repository is located.
  5. Create a scheduled task (in Windows). This is the command (edit the path to cmd.exe accordingly): C:\Windows\System32\cmd.exe /c c:\tools\chocolateypackageupdater\ketarinupdate.cmd
  6. Alternatively to stop the command window from opening on Windows, you can create a VBS script as well and put the path to the .vbs file instead of ketarinupdate.cmd as the command to run. The file should have the following:

    Set objShell = WScript.CreateObject("WScript.Shell")
    objShell.Run("C:\tools\ChocolateyPackageUpdater\ketarinupdate.cmd"), 0, True
  7. Choose a schedule for the task. Some folks run the task about once an hour to catch updates as quickly as they happen.
  8. Open Ketarin. Choose File –> Settings.
  9. Now Click Import...
  10. Choose setup/KetarinSettings.xml from the repo folder. This is going to add everything in that you will need for settings.
  11. Click on Global Variables. Ensure all of the variables are set appropriately.
    Ketarin Global Variables

This gets Ketarin all set up with a global command for all packages we create.

NOTE: This has set up global commands for "Before updating an application" and "After updating an application". Those should not need adjusting, however if you do, please be sure to export the settings again.

Create an Automatic Package

Preferably you are taking an existing package that you have tested and converting it to an automatic package.

Create a package for automatic packaging

When you are creating packages, you should ensure you are on the latest version of Chocolatey. This means you have the latest fixes to packaging templates and latest and greatest in the way of automation.

  1. Ensuring you are on the latest version of Chocolatey - choco upgrade chocolatey.
  2. Open PowerShell (or cmd.exe) and head to the automatic package folder you are using. This should be "repolocation\automatic".
  3. Run choco new <name> --auto [options]. You can use a different package template if you have those installed - see https://chocolatey.org/docs/commands-new for all options or run choco new -?. For package templates, see https://chocolatey.org/docs/how-to-create-custom-package-templates.
  4. Inspect the output. Merge in your existing package logic if you have an existing package you are converting.
  5. Ensure that checksumType and checksumType64 is sha256 as this is the type the updater will generate.
  6. Make any adjustments you need to the package to prepare for packaging.

Ketarin

  1. Open Ketarin. Choose File –> Import...
  2. Choose ketarin/_KetarinChocolateyTemplate.xml from the repo folder.
  3. Answer the questions. This will create a new job for Ketarin to check.
  4. One important thing to keep in mind is that the name of the job needs to match the name of the package folder and nuspec exactly.
  5. Right click on that new job and select Edit. Take a look at the following:
    Ketarin Job Main
  6. Click on Variables on the right of URL
    Ketarin Job Variables
  7. On the left side you should see a variable for version and one for url64. Click on version.
  8. Choose the appropriate method for you. Here I've chosen Content from URL (start/end).
  9. Enter the URL for versioning information.
    Ketarin Job Variables
  10. In the contents itself, highlight enough good information before a version to be able to select it uniquely during updates (but not so much it doesn't work every time as the page changes). Click on Use selection as start.
  11. Now observe that it didn't jump back too far.
  12. Do the same with the ending part, keeping in mind that this side doesn't need to be too much because it is found AFTER the start. Once selected click on Use selection as end.
  13. It should look somewhat similar to have is presented in the picture above.
  14. If you have a 64bit url you want to get, do the same for the url64 variable.
  15. When all of this is good, click OK.
  16. Click OK again.

Notes about tri-packages (meta/virtual aka , .install, and *.portable)

UPDATE AUG 2016: This may no longer be true. Just set up three jobs.

When you have the three packages, you should set up only two jobs, one for .install and one for .portable.

In whichever job the meta package points to, you should add a command to that like you did for the settings for all jobs in ketarin.

  1. Click on the Commands Tab and set Edit command for event to "Before updating an application".
    Ketarin Settings
  2. Add the following text (replace name with the actual name of the meta package folder):

    chocopkgup /p name /v {version} /u "{preupdate-url}" /u64 "{url64}" /pp "{file}" /c "{Checksum}" /c64 "{Checksumx64}"
    REM /disablepush
  3. Check the bottom of this section to be sure it set to Command.
    Ketarin Settings Command

Testing Ketarin/ChocoPkgUp:

  1. We need to get a good idea of whether this will work or not.
  2. Open a command line and type ketarin.
  3. Once Ketarin opens, open global options (steps 8 and 11), go to Global Variables and set cscript to 1 instead of 2 so that it only goes as far as creating packages.
  4. Find your job, and right click -> Update. If everything is set good, in moments you will have a Chocolatey package in the folder you set under {PackagesFolder}\_output, where {PackagesFolder} is the path you set in the course of the Setup section of this article.
  5. Inspect the resulting Chocolatey package(s) for any issues.
  6. You should also test the scheduled task works appropriately.

Troubleshooting/Notes

Important notes for files hosted on SourceForge

Try this first:

It isn't uncommon that certain SorceForge mirrors go offline or are extremely slow because of overload. Thus it is not recommended to use direct mirror links (e.  g. http://heanet.dl.sourceforge.net/project/...) in your chocolateyInstall.ps1 file, because this will frequently break your package and makes it unreliable.
To avoid this, use the following convention for files hosted on SourceForge: