Skip to content

Latest commit

 

History

History
280 lines (205 loc) · 16.7 KB

README.md

File metadata and controls

280 lines (205 loc) · 16.7 KB
Raw

C4B Quick-Start Guide - Supporting Scripts

This repository contains a set of supporting scripts used for the Chocolatey for Business (C4B) Quick-Start Guide (QSG).

These scripts can be used to assist in setup of a brand new Windows Server as a C4B Server.

Below is the Quick Start Guide as it exists currently on the Chocolatey Docs.

Welcome to the Chocolatey of 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 V3 Repository (Nexus)
  • Chocolatey Central Management (CCM)
  • 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 V3 Repository Server App (Nexus): Chocolatey works best with a NuGet V3 repository. This application hosts and manages versioning of your Chocolatey package artifacts, in their enhanced NuGet package (.nupkg) file format. The quick start guide helps 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 2022)
  • 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

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.

📝Offline Install: If your C4B server does not have unrestricted access to the internet, you can download the choco-quickstart-scripts repository to a Windows machine that is connected to the internet and run OfflineInstallPreparation.ps1. This will use Chocolatey to save all of the required assets into the repository folder, which can then be transferred to the target C4B server.

  • Download choco-quickstart-scripts by clicking here.
  • Unzip it, e.g.: Expand-Archive -Path ~\Downloads\choco-quickstart-scripts-main.zip -DestinationPath ~\Downloads\choco-quickstart-scripts.
  • Run the OfflineInstallPreparation script, e.g.: ~\Downloads\choco-quickstart-scripts\choco-quickstart-scripts-main\OfflineInstallPreparation.ps1.
  • Run the following to zip up your offline bundle: Compress-Archive -Path ~\Downloads\choco-quickstart-scripts\choco-quickstart-scripts-main\* -DestinationPath ~\Downloads\C4B-Files.zip.
  • Transfer the C4B-Files.zip from your downloads folder to your offline system. All further steps will be carried out on the offline system.
  • Run Expand-Archive -Path \path\to\C4B-Files.zip -DestinationPath C:\choco-setup\files -Force on your offline system.
  • Run Set-Location "$env:SystemDrive\choco-setup\files"; Set-ExecutionPolicy Bypass Process; .\Start-C4bSetup.ps1 on your offline system.
  • Proceed to Step 2!

Step 1: Begin C4B Setup

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

  1. Open a Windows 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
Invoke-RestMethod https://ch0.co/qsg-go | Invoke-Expression
    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

📝Offline Install: You can now copy the C:\choco-setup\ directory to any computer to continue the installation. To zip up that directory, run Compress-Archive -Path C:\choco-setup\files\* -DestinationPath C:\choco-setup\C4B-Files.zip. Move the archive to your new machine, and run Expand-Archive -Path /path/to/C4B-Files.zip -DestinationPath C:\choco-setup\files -Force. You should then run Set-Location "$env:SystemDrive\choco-setup\files"; .\Start-C4bSetup.ps1, and continue with the guide.

Step 2: Nexus Setup

  1. In the same elevated Windows 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: Chocolatey Central Management 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 Chocolatey Central Management packages (database, service, web), with correct parameters
    • Outputs data to a JSON file to pass between scripts

Step 4: 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
    • Updates Jenkins plugins
    • Configures pre-downloaded Jenkins scripts for Package Internalizer automation
    • Sets up pre-defined Jenkins jobs for the scripts above

Step 5: 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.

    📝 NOTE A Role and User credential will be configured to limit access to your Nexus repositories. As well, CCM Client and Service Salts are configured to further encrypt your connection between CCM and your endpoint clients. These additional settings are also incorporated into your Register-C4bEndpoint.ps1 script for onboarding endpoints.

    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
    • 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: Verification

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

    Set-Location "$env:SystemDrive\choco-setup\files"
.\Start-C4bVerification.ps1 -Fqdn '<Your expected fqdn here>'

    If you expect services to be available at chocoserver.yourcompany.com, then your command would look like: .\Start-C4bVerification.ps1 -Fqdn 'chocoserver.yourcompany.com'

    What does this script do? (click to expand)
    • Verifies Nexus Repository installation
    • Verifies Central Management installation
    • Verifies Jenkins installation
    • Ensures system firewall is configured
    • Ensures Windows Features are installed
    • Ensures services are correctly configured
    • Ensured README is created

Step 7: 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:

YouTube Video