Create Chocolatey Package with Build and Deploy Pipeline

[boexler]

Create Chocolatey Package for NLogViewer Client Application

Overview

Create a Chocolatey package for the NLogViewer Client Application to enable easy installation and distribution via the Chocolatey package manager. This includes setting up automated build and deployment pipelines.

Objectives

1. Create Chocolatey Package Specification

   • Define package metadata (nuspec file)
   • Configure installation/uninstallation scripts
   • Handle dependencies (e.g., .NET 8 runtime if needed)
   • Package the MSI installer or application binaries

2. Build Pipeline Integration

   • Integrate Chocolatey package creation into existing build process
   • Automate package versioning (using GitVersion)
   • Generate .nupkg file during CI/CD

3. Deployment Pipeline

   • Automate publishing to Chocolatey Community Repository
   • Set up release workflow for package updates
   • Handle package approval process

Technical Requirements

Package Structure

chocolatey/
├── nlogviewer-clientapplication.nuspec
├── tools/
│   ├── chocolateyinstall.ps1
│   ├── chocolateyuninstall.ps1
│   └── chocolateyBeforeModify.ps1
└── README.md

Package Details

• Package ID: nlogviewer-clientapplication (or nlogviewer)
• Description: Standalone log viewer for NLog logs via UDP network protocol or log files
• Author: Dominic Böxler
• Project URL: https://github.com/boexler/NLogViewer
• License: See LICENSE.md
• Tags: nlog, logging, log-viewer, wpf, windows

Installation Requirements

• Installation Method: Use existing MSI installer from WiX project
• Installation Path: Program Files (per-machine installation)
• Shortcuts: Start Menu and Desktop shortcuts (already configured in MSI)
• Dependencies:
  • .NET 8 Runtime (if not self-contained)
  • Or ensure self-contained deployment is used

Version Management

• Use GitVersion for automatic versioning
• Sync package version with application version
• Follow Semantic Versioning (SemVer) for Chocolatey compatibility

Implementation Tasks

Phase 1: Package Creation

• Create chocolatey/ directory structure
• Create nuspec file with package metadata
• Create installation script (chocolateyinstall.ps1)
  • Download/use MSI installer
  • Silent installation
  • Error handling
• Create uninstallation script (chocolateyuninstall.ps1)
  • Silent uninstallation
  • Cleanup verification
• Create before-modify script (chocolateyBeforeModify.ps1)
  • Handle upgrades gracefully
• Test package locally using choco pack and choco install --source .

Phase 2: Build Integration

• Add Chocolatey package build step to build pipeline
• Configure MSBuild/CI to:
  • Build the application
  • Build the WiX installer (MSI)
  • Create Chocolatey package from MSI
  • Version the package using GitVersion
• Add package validation (linting, testing)
• Generate package artifacts for release

Phase 3: Deployment Pipeline

• Set up GitHub Actions workflow (or existing CI system)
• Configure Chocolatey API key as secret
• Create release workflow that:
  • Triggers on tag/release creation
  • Builds and packages the application
  • Validates the Chocolatey package
  • Publishes to Chocolatey Community Repository
• Add manual approval step (if required)
• Set up notifications for deployment status

Phase 4: Documentation

• Update README with Chocolatey installation instructions
• Document package maintenance process
• Add troubleshooting guide
• Create package submission checklist

CI/CD Pipeline Structure

Build Pipeline Steps

1. Restore Dependencies

   - name: Restore NuGet packages
   - name: Install WiX Toolset (if needed)

2. Build Application

   - name: Build NLogViewer.ClientApplication
   - name: Publish self-contained application

3. Build Installer

   - name: Build WiX MSI installer

4. Create Chocolatey Package

   - name: Pack Chocolatey package
   - name: Validate package (choco lint)
   - name: Test package installation (choco install --source .)

5. Publish Artifacts

   - name: Upload .nupkg artifact

Release Pipeline Steps

1. Trigger: On tag/release creation (e.g., v*.*.*)
2. Build: Run build pipeline
3. Validate: Package validation and testing
4. Publish: Push to Chocolatey Community Repository

   choco push nlogviewer-clientapplication.*.nupkg --source https://push.chocolatey.org/ --api-key $env:CHOCOLATEY_API_KEY

Testing Checklist

• Package installs successfully on clean Windows system
• Application launches correctly after installation
• Shortcuts are created in Start Menu and Desktop
• Uninstallation removes all files and shortcuts
• Upgrade from previous version works correctly
• Package passes choco lint validation
• Package passes choco install --source . test

Chocolatey Repository Requirements

• Create Chocolatey account (if not exists)
• Verify email address
• Generate API key for automated publishing
• Review Chocolatey package requirements: https://docs.chocolatey.org/en-us/create/create-packages
• Ensure package follows naming conventions
• Prepare package description and tags

Additional Considerations

1. Self-Contained vs Framework-Dependent

   • Current project uses self-contained deployment (SelfContained=true)
   • Ensure MSI includes all dependencies
   • Or add .NET 8 runtime as Chocolatey dependency

2. Package Size

   • Monitor package size (Chocolatey has limits)
   • Consider using download URLs if package is too large
   • Use checksums for verification

3. Update Mechanism

   • Implement proper upgrade handling
   • Preserve user settings during upgrades
   • Handle configuration file migrations if needed

4. Security

   • Sign the package (optional but recommended)
   • Use secure download methods
   • Verify checksums

Resources

• Chocolatey Package Creation Guide
• Chocolatey Package Guidelines
• Chocolatey Automation
• GitVersion Documentation

Acceptance Criteria

• Chocolatey package can be installed via choco install nlogviewer-clientapplication
• Package is automatically built on each release
• Package is automatically published to Chocolatey Community Repository
• Package passes all Chocolatey validation checks
• Documentation is updated with installation instructions
• Package maintenance process is documented

Related Issues

• Consider linking to any existing installer or deployment issues
• May relate to versioning or release automation tasks