C4B Quick Start Guide V2

C4B Quick Start Guide V2

Welcome to the Chocolatey for Business (C4B) Quick-Start Guide! This guide will walk you through the basics of configuring a C4B Server on your VM infrastructure of choice. This includes the Chocolatey Licensed components, a NuGet V2 Repository (Nexus), Chocolatey Central Management (CCM), and an Automation Pipeline (Jenkins).

📝 NOTE

This quick-start guide is intended for customers who have recently purchased Chocolatey for Business (C4B), or are evaluating C4B as part of a proof-of-concept. It is opinionated, and thus illustrates only one method of setting up your Chocolatey environment. Our goal is to get you up-and-running smoothly and efficiently in order to fully test out the feature set. For a more exhaustive reference of possible setup scenarios, you may refer to the Organizational Deployment Documentation.

If you have any questions or would like to discuss more involved implementations, please feel free to reach out to your Chocolatey representative.

Let's get started!

Components


Chocolatey for Business Server Components

As illustrated in the diagram above, there are four main components to a Chocolatey for Business installation:

  1. C4B Licensed components: A licensed version of Chocolatey includes:

    • Installation of the Chocolatey OSS client package itself (chocolatey)
    • Chocolatey license file (chocolatey.license.xml) installed in the correct directory (ProgramData\chocolatey\license)
    • Installation of the Chocolatey Licensed extension (chocolatey.extension), giving you access to features like Package Builder, Package Internalizer, etc. (full list here).

  2. NuGet V2 Repository Server App (Nexus): Chocolatey works best with a NuGet V2 repository. This application hosts and manages versioning of your Chocolatey package artifacts, in their enhanced NuGet package (.nupkg) file format. This guide will help you setup Sonatype Nexus Repository Manager (OSS).

  3. Chocolatey Central Management (CCM): CCM is the Web UI portal for your entire Chocolatey environment. Your endpoints check-in to CCM to report their package status. This includes the Chocolatey packages they have installed, and whether any of these packages are outdated. And now, with CCM Deployments, you can also deploy packages or package updates to groups of endpoints, as well as ad-hoc PowerShell commands. CCM is backed by an MS SQL Database. This guide will set up MS SQL Express for you.

  4. Automation Pipeline (Jenkins): A pipeline tool will help you automate repetitive tasks, such checking for updates to a set of Chocolatey Packages from the Chocolatey Community Repository (CCR). If updates exist, the pipeline task will auto-internalize your list of packages, and push them into your NuGet repository for you. This guide will help you set up Jenkins as your automation pipeline.

Requirements

Below are the minimum requirements for setting up your C4B server via this guide:

  • Windows Server 2019+ (ideally, Windows Server 2019)
    • Windows Server 2016 is technically supported, but not recommended as it is nearing End-of-Life; also, you will require an additional setup script.
  • 4+ CPU cores (more preferred)
  • 16 GB+ RAM (8GB as a bare minimum; 4GB of RAM is reserved specifically for Nexus)
  • 500 GB+ of free space for local NuGet package artifact storage (more is better, and you may have to grow this as your packages and versions increase)
  • Open outgoing (egress) Internet access
  • Administrator user rights

[IMPORTANT] All commands should be run from an elevated PowerShell window (and not ISE), by opening your PowerShell console with the Run as Administrator option.

Installation

Step 0: Preparation of C4B Server

  1. Provision your C4B server on the infrastructure of your choice.

  2. Install all Windows Updates.

  3. If you plan on joining this server to your Active Directory domain, do so now before beginning setup below.

  4. If you plan to use a Purchased/Acquired or Domain SSL certificate, please ensure the CN/Subject value matches the DNS-resolvable Fully Qualified Domain Name (FQDN) of your C4B Server. Place this certificate in the Local Machine > Personal certificate store, and ensure that the private key is exportable.

  5. Copy your chocolatey.license.xml license file (from the email you received) onto your C4B Server.

⚠️DISCLAIMER: This guide utilizes code from a GitHub repository, namely: choco-quickstart-scripts. Though we explain what each script does in drop-down boxes, please do your due diligence to review this code and ensure it meets your Organizational requirements.

Step 1: Begin C4B Setup

  1. Open a PowerShell console with the Run as Administrator option, and paste and run the following code:

    Set-ExecutionPolicy Bypass -Scope Process -Force
    [Net.ServicePointManager]::SecurityProtocol = [Net.SecurityProtocolType]::tls12
    $QuickStart = 'https://raw.githubusercontent.com/chocolatey/choco-quickstart-scripts/main/Start-C4bSetup.ps1'
    Invoke-Expression -Command ((New-Object System.Net.WebClient).DownloadString($QuickStart))
    
    What does this script do? (click to expand)
    • Installs Chocolatey client from https://community.chocolatey.org
    • Prompts for your C4B license file location, with validation
    • Converts your C4B license into a Chocolatey package
    • Configures local "choco-setup" directories
    • Downloads setup files from "choco-quickstart-scripts" GitHub repo
    • Downloads Chocolatey packages required for setup

Step 2: Nexus Setup

  1. In the same elevated PowerShell console as above, paste and run the following code:

    Set-Location "$env:SystemDrive\choco-setup\files"
    .\Start-C4bNexusSetup.ps1
    
    What does this script do? (click to expand)
    • Installs Sonatype Nexus Repository Manager OSS instance
    • Cleans up all demo repositories on Nexus
    • Creates a "ChocolateyInternal" NuGet repository
    • Creates a "ChocolateyTest" NuGet repository
    • Creates a "choco-install" raw repository
    • Sets up "ChocolateyInternal" on C4B Server as source, with API key
    • Adds firewall rule for repository access
    • Installs MS Edge, and disables first-run experience
    • Outputs data to a JSON file to pass between scripts

Step 3: CCM Setup

  1. In the same PowerShell Administrator console as above, paste and run the following code:

    Set-Location "$env:SystemDrive\choco-setup\files"
    .\Start-C4bCcmSetup.ps1
    
    What does this script do? (click to expand)
    • Installs MS SQL Express and SQL Server Management Studio (SSMS)
    • Creates "ChocolateyManagement" database, and adds appropriate `ChocoUser` permissions
    • Installs all 3 CCM packages (database, service, web), with correct parameters
    • Outputs data to a JSON file to pass between scripts

    ⚠️WARNING: Only if you choose to run this on a Windows Server 2016 VM, you will require a reboot before IIS is completely installed. The script above will notify you of this. Once the reboot is complete and you log back in, you will also have to paste and run the following code in a PowerShell Administrator console:

    Set-Location "$env:SystemDrive\choco-setup\files\scripts"
    .\Start-C4bCcmSetup2.ps1
    

Step 4: SSL Setup

  1. In the same elevated PowerShell console as above, paste and run the following code:

    Set-Location "$env:SystemDrive\choco-setup\files"
    .\Set-SslSecurity.ps1
    

    ALTERNATIVE 1 : Custom SSL Certificate - If you have your own custom SSL certificate (purchased/acquired, or from your Domain CA), you can paste and run the following script with the Thumbprint value of your SSL certificate specified:

    Set-Location "$env:SystemDrive\choco-setup\files"
    .\Set-SslSecurity.ps1 -Thumbprint '<YOUR_CUSTOM_SSL_CERT_THUMBPRINT_HERE>'
    

    ⚠️REMINDER: If you are using your own SSL certificate, be sure to place this certificate in the Local Machine > Personal certificate store before running the above script, and ensure that the private key is exportable.

    ALTERNATIVE 2 : Wildcard SSL Certificate - If you have a wildcard certificate, you will also need to provide a DNS name you wish to use for that certificate:

    Set-Location "$env:\SystemDrive\choco-setup\files"
    .\Set-SslSecurity.ps1 -Thumbprint '<YOUR_CUSTOM_SSL_CERT_THUMBPRINT_HERE>' -CertificateDnsName '<YOUR_DESIRED_FQDN_HERE>'
    

    For example, with a wildcard certificate with a thumbprint of deee9b2fabb24bdaae71d82286e08de1 you wish to use chocolatey.foo.org, the following would be required:

    Set-Location "$env:SystemDrive\choco-setup\files"
    .\Set-SslSecurity.ps1 -Thumbprint deee9b2fabb24bdaae71d82286e08de1 -CertificateDnsName chocolatey.foo.org
    

    What does this script do? (click to expand)
    • Adds SSL certificate configuration for Nexus and CCM web portals
    • Generates a `Register-C4bEndpoint.ps1` script for you to easily set up endpoint clients
    • Outputs data to a JSON file to pass between scripts

Step 5: Jenkins Setup

  1. In the same elevated PowerShell console as above, paste and run the following code:

    Set-Location "$env:SystemDrive\choco-setup\files"
    .\Start-C4bJenkinsSetup.ps1
    
    What does this script do? (click to expand)
    • Installs Jenkins package (pinned to a specific version)
    • Updates Jenkins plugins
    • Configures pre-downloaded Jenkins scripts for Package Internalizer automation
    • Sets up pre-defined Jenkins jobs for the scripts above
    • Writes a Readme.html file to the Public Desktop with account information for C4B services
    • Auto-opens README, CCM, Nexus, and Jenkins in your web browser
    • Removes temporary JSON files used during provisioning

    🔍 FYI: A Readme.html file will now be generated on your desktop. This file contains login information for all 3 web portals (CCM, Nexus, and Jenkins). This Readme.html, along with all 3 web portals, will automatically be opened in your browser.

Step 6: Setting up Endpoints

  1. Find the Register-C4bEndpoint.ps1 script in the choco-setup\files\scripts\ directory on your C4B Server. Copy this script to your client endpoint.

  2. Open an elevated PowerShell console on your client endpoint, and browse (cd) to the location you copied the script above. Paste and run the following code:

    Set-ExecutionPolicy Bypass -Scope Process -Force
    [Net.ServicePointManager]::SecurityProtocol = [Net.SecurityProtocolType]::tls12
    .\Register-C4bEndpoint.ps1
    
    What does this script do? (click to expand)
    • Installs Chocolatey client (chocolatey), using a script from your raw "choco-install" repository
    • Runs the "ClientSetup.ps1" script from your raw "choco-install" repository, which does the following:
    • Licenses Chocolatey by installing the license package (chocolatey-license) created during QDE setup
    • Installs the Chocolatey Licensed Extension (chocolatey.extension) without context menus
    • Configures "ChocolateyInternal" source
    • Disables access to the "chocolatey" public Chocolatey Community Repository (CCR)
    • Configures Self-Service mode and installs Chocolatey GUI (chocolateygui) along with its licensed extension (chocolateygui.extension)
    • Configures Central Management (CCM) check-in, and opts endpoints into CCM Deployments

Conclusion

Congratulations! If you followed all the steps detailed above, you should now have a fully functioning Chocolatey for Business implementation deployed in your environment.

It is worth mentioning that some customers may have a more bespoke environment, with the presence of proxies and additional configuration management applications. Chocolatey is engineered to be quite flexible, specifically to account for these scenarios. Please refer to the many options for installation referenced on the Installation page. Again, If you have any questions or would like to discuss more involved implementations, please feel free to reach out to your Chocolatey representative.

See it in Action

If you'd prefer to watch and follow along, here is a recording of our Chocolatey Team going through this guide live on our Twitch stream: