chocolatey/choco-quickstart-scripts

C4B Quick-Start Guide - Supporting Scripts

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

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.

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>' -Hardened

   ⚠️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 You may have noticed the -Hardened parameter we've added above. When using a custom SSL certificate, this parameter will further secure access to your C4B Server. 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. We do require you to enable this option if your C4B Server will be Internet-facing, with a FQDN that resolves to a public IP.

   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>' -Hardened

   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 -Hardened

   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

choco-quickstart-scripts's Issues

Move repo to Chocolatey org

In preparation for launch of the guide, it needs moving to the chocolatey organization.

The transfer has already happened, but we will need to adjust all the scripting to point to the new location for the repo.

Specifically, the Start-C4bSetup.ps1 needs to be updated here:

choco-quickstart-scripts/Start-C4BSetup.ps1

Line 95 in f51517c

$QsRepo = "https://github.com/adilio/choco-quickstart-scripts/archive/main.zip"

Also, the Readme itself, in Step 1:
https://github.com/chocolatey/choco-quickstart-scripts/blob/main/README.md#step-1-preparation-of-c4b-server

We'll have to go through and ensure that no other references are out-of-date.

Add --no-progress on install calls

When we run choco install we should pass --no-progress to keep output trimmed down.

Jenkins web does not come up consistently (service is started)

When @ryanrichter94 runs the QuickStart scripts on his old Windows Server 2019 VM, he is intermittently seeing failures in the Jenkins website coming up.

Usually, a Restart-Service Jenkins brings it up fine, but incorporating this step into the script itself does not work.

Further troubleshooting and repro may be needed.

Add Choco APIKey Entry for ChocolateyInternal Source After SSL is Configured

Need to add a choco apikey command to the SSL script right after this line:

choco-quickstart-scripts/Set-SslSecurity.ps1

Line 104 in 63d7512

choco source add --name="'ChocolateyInternal'" --source="'$RepositoryUrl'" --priority=1

Can take this line out of the Nexus script:

choco-quickstart-scripts/Start-C4bNexusSetup.ps1

Line 62 in 63d7512

choco apikey -s 'ChocolateyInternal' -k $NugetApiKey

File Paths For Jenkins Jobs Have Wrong Syntax in File Paths

In the Jenkins jobs Update test repo from CCM and Update Prod Repo the file paths in the powershell within Jenkins are wrong.

Popup web pages for user at end of scripts (enhancement)

This is purely an enhancement to improve the User Experience.

It would be handy to automatically open all 3 web portals (CCM, Nexus, Jenkins) in the user's web browser.

This prompt could allow a pressing of any key to override, but otherwise proceed to just open the sites in a browser after, let's say, 10 seconds.

Fixup Nexus install

Leverage stuff from TreasureChest so we can use the API directly without needing to mess with script execution settings.

Server 2016 requires reboot after IIS install (Start-C4bCCMSetup.ps1)

The following line in the Start-C4bCCMSetup.ps1 script on a Windows Server 2016 box installs IIS:

choco-quickstart-scripts/Start-C4bCcmSetup.ps1

Line 160 in c1c3827

choco install IIS-WebServer -s windowsfeatures --no-progress -y

However, on a Windows Server 2016 box, a reboot is required before IIS install completes. None of the IIS components are available to the later parts of this script, in setting up the requisite installs for chocolatey-management-web.

This issue does not occur in Windows Server 2019 or 2022. We will have to adjust the setup scripts to account for this difference in some way.

Make Nexus SSL config idempotent

The following code that edits the Nexus config makes the Set-SslSecurity.ps1 unable to be run multiple times, if needed:

choco-quickstart-scripts/scripts/Get-Helpers.ps1

Lines 1011 to 1028 in 61f860c

	$nexusPath = 'C:\ProgramData\sonatype-work\nexus3'
	$configPath = "$nexusPath\etc\nexus.properties"
	$configString = @'
	jetty.https.stsMaxAge=-1
	application-port-ssl=8443
	nexus-args=${jetty.etc}/jetty.xml,${jetty.etc}/jetty-https.xml,${jetty.etc}/jetty-requestlog.xml
	'@
	$configString | Add-Content -Path $configPath
	$xmlPath = 'C:\ProgramData\nexus\etc\jetty\jetty-https.xml'
	[xml]$xml = Get-Content -Path 'C:\ProgramData\nexus\etc\jetty\jetty-https.xml'
	foreach ($entry in $xml.Configure.New.Where{ $_.id -match 'ssl' }.Set.Where{ $_.name -match 'password' }) {
	$entry.InnerText = $passkey
	}
	$xml.OuterXml | Set-Content -Path $xmlPath

We'd like to make this idempotent.

SSL Setup doesn't need CCM bindings

The CCM service runs on Kestrel in DotNet Core now, no need to fix bindings as it is all in-proc.

Emit Services information to desktop (Readme)

At the end of the entire process we need to drop a document on the desktop with url and default account information for all services provisioned as part of the guide.

Update Start-C4bSetup.ps1 to not use short URI's

Currently, the Start-C4bSetup.ps1 script utilizes ch0.co short URI's as a convenience for the user. As some organizations block the usage of short URI's for security (although one could argue that's counter-intuitive), it would behoove us to use the raw file URI's directly from this repo.

ChocolateyInternal Source Entry Not Updated After Running Set-SslSecurity.ps1

Description

The Chocolatey Source entry for the ChocolateyInternal Source never gets updated within Chocolatey via a choco source add command after Set-SslSecurity.ps1 is run. Thus the wrong port number for nexus is being used. It needs changing from the default 8081 to 8443 when enabling SSL.

Console Output

This is my Chocolatey source entry after running the Set-SslSecurity.ps1. I tried installing the chocolatey-agent package which i confirmed is on my ChocolateyInternal repository. Also verified my repo is accessable at https://chocosever:8443

Chocolatey v0.10.15 Business
Installing the following packages:
chocolatey-agent
By installing you accept licenses for the packages.
Error retrieving packages from source 'http://localhost:8081/repository/ChocolateyInternal/':
 Unable to connect to the remote server
Progress: Downloading chocolatey-agent 0.11.2... 100%

chocolatey-agent v0.11.2
chocolatey-agent package files install completed. Performing other installation steps.
Installing Windows service named 'chocolatey-agent' pointing to 'C:\ProgramData\chocolatey\lib\chocolatey-agent\tools\service\chocolatey-agent.exe'...
Installing service chocolatey-agent...
Service chocolatey-agent has been successfully installed.
Creating EventLog source chocolatey-agent in log Application...
Windows service named 'chocolatey-agent' successfully installed.
Starting Windows service named 'chocolatey-agent' if it is not running...
 The install of chocolatey-agent was successful.
  Software install location not explicitly set, could be in package or
  default install location if installer.

Chocolatey installed 1/1 packages.
 See the log for details (C:\ProgramData\chocolatey\logs\chocolatey.log).
PS C:\choco-setup\files\scripts> choco source
Chocolatey v0.10.15 Business
chocolatey - https://chocolatey.org/api/v2/ | Priority 0|Bypass Proxy - False|Self-Service - False|Admin Only - False.
chocolatey.licensed - https://licensedpackages.chocolatey.org/api/v2/ (Authenticated)| Priority 10|Bypass Proxy - False|Self-Service - False|Admin Only - False.
ChocolateyInternal - http://localhost:8081/repository/ChocolateyInternal/ | Priority 1|Bypass Proxy - False|Self-Service - False|Admin Only - False.
PS C:\choco-setup\files\scripts>

Update Readme doc to reflect new process

The main README.md file contains a draft of the actual QuickStart Guide V2 that we plan to PR to docs.chocolatey.org.

This doc needs to be updated to reflect the new process.

SSL Setup doesn't support wildcard certs

This is a bit of a problem, and we need to support them similarly to how we do in QDE.

Unattended Mode option

It would be great to have a method for triggering the entire QuickStart process, without having to run each script one-by-one. This would make testing easier as well.

Unable to complete agent check-in to CCM

As per #85 which installs chocolatey-agent on the server, and then checks in to CCM, the C4B Server is not checking into itself.

The agent log states the following:

2021-10-22 14:45:41,972 6 [ERROR] - Unable to set up central management reporting and checking for
 deployments. It appears you've enabled the feature
 'useChocolateyCentralManagement', but you have not defined the
 management service url. Please ensure you set the configuration
 value centralManagementServiceUrl (e.g. 'choco config
 set centralManagementServiceUrl
 https://<location>:<port>/ChocolateyManagementService'). For more
 information, please see
 https://chocolatey.org/docs/features-chocolatey-central-management.

Again, @steviecoaster, assigning this you Sir. Please investigate.

Add ChocolateyTest NuGet repo

Current environments (like QDE) have a test repo setup as a best practice.

We should add one here to keep things consistent. This will benefit Jenkins setup staying the same as other env's as well.

Make Running QSG Scripts via ISE Impossible

Wanna look into making it so if you attempt to call any of the QSG setup scripts via the Powershell_ISE.exe application. Powershell will throw an error saying to not do this and run via Windows Powershell.

Add additional security - ability to define your own SSL certificate

These tasks were split out from #9, and include:

• Secure Nexus repo with credential
• Turn on CCM Client & Service Salts
• Generate Register-InternetEndpoint.ps1 script to pair with a ClientSetup.ps1 script

Add Pre-Flight Checks to initial scripting

As a way to help users fall only into the "Pit of Success" (😂), it would be helpful to have some pre-flight checks run by the user, to ensure they have all the pieces in place before beginning to deploy. This could be Pester tests, or simple functions that check for certain prerequisites. This process could also be interactive, to get input from the end-user as well.

Some ideas for prerequisites to check for:

• Does the C4B Server have Internet access?
• Is it going to be Internet-enabled? If so:
  • Do you have a public IP?
  • Do you have a Fully-Qualified Domain Name (FQDN) resolving to that public IP?
  • Do you have an SSL certificate with an exportable private key for this FQDN?

DateTime value in transcript file names is in incorrect format

Currently, all the setup scripts referenced in this guide start with a Start-Transcript command, that has a malformed format:

choco-quickstart-scripts/Start-C4BSetup.ps1

Line 26 in c1c3827

Start-Transcript -Path "$env:SystemDrive\choco-setup\logs\Start-C4bSetup-$(Get-Date -Format 'yyyyMMdd-hhmmss').txt"

Current:
Get-Date -Format 'yyyyMMdd-hhmmss'

Should be:
`Get-Date -Format 'yyyyMMdd-HHmmss'

This should be an easy fix; documented here for clarity.

Change Choco Install to Choco Upgrade Commands

Small enhancement is to call the following lines in the client setup file as choco upgrade calls instead of currently being choco install ones. Mainly to make the script more idempotent in case any of these packages are already installed on an endpoint you run the Register-C4bEndpoint.ps1 script against.

Lines to change for reference:

choco-quickstart-scripts/scripts/ClientSetup.ps1

Lines 105 to 110 in 63d7512

	choco install chocolatey-license -y --source="'ChocolateyInternal'"
	choco install chocolatey.extension -y --params="'/NoContextMenu'" --source="'ChocolateyInternal'" --no-progress
	choco install chocolateygui -y --source="'ChocolateyInternal'" --no-progress
	choco install chocolateygui.extension -y --source="'ChocolateyInternal'" --no-progress
	choco install chocolatey-agent -y --source="'ChocolateyInternal'"

Align Jenkins configuration to be in-line with QDE Appliance

In the appliance, scripts that Jenkins jobs rely on live on the root of C:\ in a scripts folder.

To provide parity with the appliance experience, we need to adjust the way we handle the configuration of Jenkins during that step of the Guide.

Add SSL Configuration for Nexus and CCM Web

Add similar functionality to the New-SSLCertificate.ps1 Set-QdeInternetSecurity.ps1 script, which do the following:

• Generate a new SSL cert
• Add cert to appropriate cert stores
• Add cert to CCM Web
• Add cert to Nexus Web

Error Running Start-C4bJenkinsSetup.ps1 When Removing JSON Files

Description of Issue

Get the following error when running the Start-C4bJenkinsSetup.ps1 in step 6 of setup. Script fails when trying to run line 172 of the script to remove the JSON files. Does not continue to prompt to bring the services sites up in browser because of this.

Console Output

Cleaning up temporary data
Remove-Item : Cannot find path 'C:\choco-setup\files\ccm.json' because it does not exist.
At C:\choco-setup\files\scripts\Get-Helpers.ps1:1104 char:70
+ ... JsonPath  -Filter '*.json' | Foreach-Object { Remove-Item $_ -Force }
+                                                   ~~~~~~~~~~~~~~~~~~~~~
    + CategoryInfo          : ObjectNotFound: (C:\choco-setup\files\ccm.json:String) [Remove-Item], ItemNotFoundExcept
   ion
    + FullyQualifiedErrorId : PathNotFound,Microsoft.PowerShell.Commands.RemoveItemCommand

CCM 0.6.0 Package installs failing

As the Chocolatey Central Management packages have been updated to v 0.6.0, we now have different dependencies required at different steps in the process as well.

Firstly the following packages now require a minimum of v 3.1.16:

• aspnetcore-runtimepackagestore
• dotnetcore-windowshosting

Also, as a result of moving to aspnet-core as a requirement, the above dependencies are now required earlier on in the scripting. Before, only CCM Web required the above. Now, CCM DB and CCM Service also depend on them.

All the above logic will need to be added to the Start-C4bCcmSetup.ps1 script.

Add Chocolatey Licensed packages back into bootstrap script

As per comments from the following PR: #28

We are planning to add back the internalization and push of Chocolatey packages form the Chocolatey Licensed feed. This will encourage usage of packages like chocolateygui.extension, as well as improve the stability of the install tasks.

Remove Edge First-Run in Nexus script

We are using the new Edge (Chromium) in this setup, as it is a Microsoft product, and thus preferred by our users when setting up Windows Servers.

As such, it would be nice to not have Edge prompt for setup on first-run. This will reduce the number of clicks. Also, these are servers, so the Admins will likely NOT be logging to their Microsoft accounts on the browser.

Change URL references in Desktop Readme to Hyperlinks

Currently the URL references for the different services on the VM are written as plain text within the Desktop Readme. Think it would be a nice to format these URLs as clickable Hyperlinks within the Readme file instead.

Error bringing up CCM Web in SSL script

When running Set-SSLSecurity.ps1, starting the ChocolateyCentralManagement has failed on one occasion with the following error:

start-webitem : The object identifier does not represent a valid object. (Exception from HRESULT: 0x800710D8)
At C:\choco-setup\files\Set-SSLSecurity.ps1:110 char:5
+     Start-Website ChocolateyCentralManagement
+     ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+ CategoryInfo          : InvalidOperation: (:) [Start-WebItem], COMException
+ FullyQualifiedErrorId : InvalidOperation,Microsoft.IIs.PowerShell.Provider.StartItemCommand

We may have to build a wait or check into this.

Hostname change

First, thanks for the updated v2 quickstart guide; it really seems to ease complexity of setup.

However, I am in need of a hostname change in the scripts and in the certificates as I'm not satisfied with the default, which is not detailed in the readme nor on the website. I do find a section on this at the QDE docs so I am assuming the same advice holds for the quickstart setup. Am I assuming this correctly? If so, I would like to suggest adding it to docs here too.

Dotnetcore-sdk package install requires confirmation

Installing the dotnetcore-sdk package in the Start-C4bCcmSetup.ps1 requires confirmation (-y).

This is something I missed when adding this dependency in the last PR. 🤦🏼

Apologies.

Move web portal popup to SSL script

This guide was originally written with the Jenkins setup as the last step. As we're now incorporating SSL setup into this guide, the SSL setup script will now be the final script. Therefore, the logic and code that pops up the 3 web portals should be moved to the end of the SSL setup script.

Add Internet-Facing Security Hardening to Nexus & CCM

When people bring their own SSL cert, we would like to support the ability to secure Nexus and CCM.

The steps for this are the same as outlined here:
https://docs.chocolatey.org/en-us/quick-deployment/setup/internet-setup#nexus-setup
https://docs.chocolatey.org/en-us/quick-deployment/setup/internet-setup#ccm-setup

Two things to tackle in Set-SslSecurity.ps1:

• Creating a ChocoRole and ChocoUser credential in Nexus (and disable anonymous access)
• Generate CCM Client & Service Salts, and add them to the Register-C4bEndpoint.ps1 script to pass to ClientSetup.ps1

Don't internalize and push one-time use packages to Nexus (speed enhancement)

Downloading, internalizing, and pushing one-time use packages is currently taking up quite a bit of setup time.

We need to explore the possibility of cutting down the amount of packages we internalize and push, especially if they will not be reused again.

In initial testing, this can potentially halve the total setup time, from 1 hour to 30 minutes.

Using regkey to change Edge first run setting fails

On Windows Server 2016 specifically, setting the following registry key fails:

choco-quickstart-scripts/Start-C4BNexusSteup.ps1

Lines 986 to 991 in c1c3827

	$RegArgs = @{
	Path = 'HKLM:\SOFTWARE\Microsoft\Edge\'
	Name = 'HideFirstRunExperience'
	Type = 'Dword'
	Value = 1
	Force = $true

Error:

Set-ItemProperty : Cannot find path 'HKLM:\SOFTWARE\Microsoft\Edge\' because it does not exist.
At C:\choco-setup\files\Start-C4BNexusSetup.ps1:993 char:5
+     Set-ItemProperty @RegArgs
+     ~~~~~~~~~~~~~~~~~~~~~~~~~
    + CategoryInfo          : ObjectNotFound: (HKLM:\SOFTWARE\Microsoft\Edge\:String) [Set-ItemProperty], ItemNotFound
   Exception
    + FullyQualifiedErrorId : PathNotFound,Microsoft.PowerShell.Commands.SetItemPropertyCommand

Update README

I have been able to consistently reproduce a bug with the generation of the Readme.html file on the desktop:

New-QuickstartReadme : The term 'https://${HostName}:8443' is not recognized as the name of a cmdlet, function, script
file, or operable program. Check the spelling of the name, or if a path was included, verify that the path is correct
and try again.
At C:\choco-setup\files\Start-C4bJenkinsSetup.ps1:177 char:1
+ New-QuickstartReadme
+ ~~~~~~~~~~~~~~~~~~~~
    + CategoryInfo          : ObjectNotFound: (https://${HostName}:8443:String) [New-QuickstartReadme], CommandNotFoun
   dException
    + FullyQualifiedErrorId : CommandNotFoundException,New-QuickstartReadme

This is called in the Start-C4bJenkinsSetup.ps1, and the code for this function is here:

choco-quickstart-scripts/scripts/Get-Helpers.ps1

Lines 1593 to 1637 in a0feced

	Function New-QuickstartReadme {
	<#
	.SYNOPSIS
	Generates a desktop README file containing service information for all services provisioned as part of the Quickstart Guide.
	.PARAMETER HostName
	The host name of the C4B instance.
	.EXAMPLE
	./New-QuickstartReadme.ps1
	.EXAMPLE
	./New-QuickstartReadme.ps1 -HostName c4b.example.com
	#>
	[CmdletBinding()]
	Param(
	[Parameter()]
	[string]
	$HostName = $(Get-Content "$env:SystemDrive\choco-setup\logs\ssl.json" | ConvertFrom-Json).CertSubject
	)
	process {
	$nexusPassword = Get-Content -Path 'C:\ProgramData\sonatype-work\nexus3\admin.password'
	$jenkinsPassword = Get-Content -path 'C:\Program Files (x86)\Jenkins\secrets\initialAdminPassword'
	$nexusApiKey = (Get-Content "$env:SystemDrive\choco-setup\logs\nexus.json" | ConvertFrom-Json).NuGetApiKey
	$tableData = @([pscustomobject]@{
	Name = 'Nexus'
	Url = "<a>$(https://${HostName}:8443)</a>"
	Username = "admin"
	Password = $nexusPassword
	ApiKey = $nexusApiKey
	},
	[pscustomobject]@{
	Name = 'Central Management'
	Url = "<a>$(https://${HostName})</a>"
	Username = "ccmadmin"
	Password = '123qwe'
	},
	[PSCustomObject]@{
	Name = 'Jenkins'
	Url = "<a>$(http://${HostName}:8080)</a>"
	Username = "admin"
	Password = $jenkinsPassword
	}
	)

This error is new, and could be the result of not testing #84 throughly enough?

@steviecoaster , I'm assigning this to you Sir.

Install chocolatey-agent on C4B Server and check in to CCM

Need to add the installation of the chocolatey-agent package onto the end of the StartC4bCcmSetup.ps1 script, so that the agent gets installed on the server itself. Mainly so you get reporting on the sever as well as a machine entry checking in when you login to CCM for the first time to verify it is working. Also it does count as a licensed machine in your licensed machine count then.

Add Self-Signed Certificate import site

In current versions of QDE, a site on port 80 hosts an "Import-ChocoServerCertificate.ps1" script, in order to help endpoint clients trust the self-signed cert of the QDE server.

The same mechanism should exist here in this guide.

ChocolateyInstall Script Needs to Not be String

Need to edit the ChocolateyInstall script to not be passed as a string as it is currently written. But to mirror how we are passing this as in QDE currently.

SSL Setup uses bad value setting nexus config

Copy/paste happy makes for a bug in a script. Quick changes to use appropriate values in a foreach loop will fix this up.

Add ClientSetup.ps1 script

This guide needs an easy ClientSetup.ps script, hosted in the raw choco-install repo, to help users easily install the requisite C4B packages on their endpoints, and onboard them to CCM.

Support newer versions of Jenkins package

As the Jenkins Chocolatey package will now be updated beyond 2.222.4, and QDE in Azure is removing the pin for this version going forward, we plan to continue our feature parity with Azure QDE by removing the pinned version for Jenkins in QSG as well.

Newer versions of Jenkins will, of course, need to be tested to support QSG code functionality. However, this issue is simply for removing the code to pin the version.

Test Guide on Windows Server 2016,2019,2022

We'd like to be able to use the QuickStart Guide on ALL currently-supported Windows Server OS's. This guide is meant to be opinionated, and as such we have no intention of supporting non-WMF/PowerShell 5.1 devices.

As such, we're looking to test the Guide on:

• Windows Server 2016
• Windows Server 2019
• Windows Server 2022

We're not as worried about 1809-20H2 releases, as supporting major version OS's above and below them should cover those as well.

Add Jenkins setup

We still require the addition of the Jenkins setup to this server. This should include:

• Choco install of the package
• Version-pinning, if required
• Pre-downloaded Jenkins scripts for Package Internalizer automation
• Pre-defined Jenkins jobs for the scripts above

Add Support for Offline QSG

This is a part of a long-term plan to support Offline mode.

We would like to have The Quick-Start Guide (QSG) work whether there is reliable access to the Chocolatey Community Repo (CCR) and Chocolatey Licensed Repo. This is important as a first step for Folks who are attempting to deploy QSG on air-gapped servers.

As well, it'll help when we demo to have a more consistent experience, not limited by bandwidth issues.

To enable this, we can take a few approaches:

1. Have a separate script that downloads/internalizes all packages and resources required for additional steps ahead of time
2. Have a pre-baked archive downloaded that contains the above

Regardless of the approach we choose, we will have to refactor the existing scripts to account for an "Offline" method. This could be as simple as an -Offline switch parameter, that gets conditionally evaluated any time there's a download step.

Update Import-ChocoServerCertificate Script to Handle SSPI Error

Go through and upgrade the Import-ChocoServerCertificate script to handle the occasional SSPI inner exception error that is scene with the current version of the script.

Add New CCM 0.6.2 DB Dependent Package to CCM Setup Script

Add as new line 88 in the Start-C4bCcmSetup.ps1.

# Starting with v0.6.2 of the CCM Database package, it uses dotnetcore-sdk so that it may be installed on a system without requiring IIS. At the time of publishing, the most recent version of this package is 3.1.410, but later package versions (within the 3.x.x release) are expected to work
choco install dotnetcore-sdk --version 3.1.410 --source $Ccr --no-progress -y

Add ability to pass JSON data between scripts

Ideally, there is data we'd like to pass between scripts (e.g. NuGet API key), that would be helpful for the user and Support to have handy. We already have transcript files, but those aren't always easy to get this info from.

For the time being, we can output these as JSON settings files from each script, that other scripts can read from.

We can always iterate a different direction later.