Desktop Readme
Desktop Readme
:choco-info: NOTE
This document is for Version 1 of the Quick Deployment Environment. If you're using a newer version of QDE, please refer to the newer QDE Desktop Readme page.
This system has been pre-configured as a fully functioning C4B environment.
:choco-warning: WARNING
Please follow these steps in exact order. These steps build on each other and need to be completed in order.
:choco-info: NOTE
This is likely more up to date than the ReadMe you will find on the desktop (not including redacted items like credentials). If there are conflicts between the desktop readme and what you see here, use this document.
Summary
To finish setting up QDE (Quick Deployment Environment), you'll need to work through this document and run the different commands you find here. Please note that nearly all the commands need to be run from an administrative context.
If you run into any issues as you set up your QDE and clients, please reach out to support at [REDACTED] and folks can set up a session to work with you on this.
Additional information can be found in our Online Documentation.
- QDE Setup
- QDE Desktop ReadMe File (online version of the desktop readme, online is most up to date)
- QDE SSL/TLS Setup
- QDE Firewall Changes
- QDE Client Setup (setting up your client machines)
Step 0: Complete Prerequisites
There are some steps you will have taken before you come to this readme. Please make sure you have taken those steps ahead of time. Please see the Online Documentation for the most up to date information.
Step 1: Expand Disk Size
On the machine, please check the size of the C drive. If it needs expanded, expand it to the space you've allocated for the machine.
# This should increase the space available on the C drive.
Resize-Partition -DriveLetter C -Size ((Get-PartitionSupportedSize -DriveLetter C).SizeMax)
Step 2: Create a License Package
To leverage all of the features of C4B, copy the license file you received via email to C:\ProgramData\chocolatey\license
.
Make sure the name of the file is exactly chocolatey.license.xml
.
In an administrative Powershell session, execute the following:
Set-ExecutionPolicy Bypass -Scope Process -Force; . 'C:\choco-setup\files\CreateLicensePackage.ps1'
This will create the licensed package at C:\choco-setup\packages
and push it up to your Nexus repository for use.
Step 3: Regenerate SSL Certificates
Under almost all circumstances for security purposes, you are going to want to complete this step. We've made it easy for you with a script. Once complete, the script will generate new SSL certificates for all services and move them to the appropriate locations and configure the services to use them. Please see SSL/TLS Setup for more details.
:choco-info: NOTE
Please run the below from an administrative PowerShell session.
Set-ExecutionPolicy Bypass -Scope Process -Force; . C:\choco-setup\files\New-SSLCertificate.ps1
:choco-warning: WARNING
This script will seemingly prompt for input, and have other strange output. This is due to poor Java tooling and console output which cannot be suppressed. Just let things happen, as things are working as expected.
:choco-warning: WARNING
Timezones are super important here and time synchronization is really important when generating SSL Certificates. You want to make sure you have this correct and good. Otherwise there is a potential edge case you could generate an SSL Certificate that is not yet valid.
Once complete, this script will generate new SSL certificates for all services and move them to the appropriate locations and configure the services to use them.
Step 4: Enable Central Management
:choco-info: NOTE
This step should only be completed once the license package has been created in the step above. All licensed features are already installed, but will not be functional without a valid license file.
Run the following to turn on the Central Management services in an administrative PowerShell session:
Set-ExecutionPolicy Bypass -Scope Process -Force; . 'C:\choco-setup\files\EnableCCM.ps1'
Step 5: Review Server Information
Nexus Repository
- Url: https://chocoserver:8443
- Username: admin
- Password: [REDACTED] (credentials included on desktop readme)
- API Key: [REDACTED] (credentials included on desktop readme)
When you first log in to Nexus, you will immediately be asked you change your password. You will then be asked if you'd like to enable Anonymous Access to the repositories. We typically recommend doing this, unless security requirements in your organization stipulate that RBAC controls be in place.
:choco-warning: WARNING
If you plan to allow clients to connect in from outside your network (over the internet), please contact support for the right options. There will be more work you'll need to do to limit access to specific repositories.
Sources configured in Chocolatey can only read data from their remote endpoints, and cannot delete items. If you need to limit the packages people have access to, control this with separate Hosted and Group repositories. Consult the Nexus documentation or reach out to Chocolatey Support for more information.
Jenkins
- Url: http://chocoserver:8080
- Username: admin
- Password: [REDACTED] (credentials included on desktop readme)
For using Jenkins, please refer to our documentation.
At most, you will need to login to Jenkins, change the password (By going to People on the Sidebar > Click on admin > Click Configure on the Sidebar, scroll down to change password section
), and enable the pre-configured jobs to run on the schedule of your choosing.
Our documentation can assist with ensuring this is done correctly.
Chocolatey Central Management
- Url: https://chocoserver
- Username: ccmadmin
- Default Password: 123qwe (You will be prompted to change this on first login)
:choco-info: NOTE
You will see 2 packages (aspnetcore-runtimepackagestore and dotnetcore-windowshosting) listed as outdated at version 2.2.7. These packages have been pinned to that version, as they are required at that level for the current version of CCM to function correctly.
Firewall ports
To allow access to all services firewall ports have been opened on QDE as follows:
- 8443: Nexus WebUI
- 8080: Jenkins WebUI
- 443: Central Management WebUI
- 24020: Central Management Service communications for Agent check-in
Browser considerations
We recommend you use Google Chrome to interact with all Web interfaces for the different services installed. You will find Google Chrome pre-installed in the environment.
Step 6: Change the API Key (Optional, Recommended)
You may wish to change the API key before you start using things. To do so, log in to Nexus using the information above, or your new credentials if you have already gone through the first run wizard. Once logged in perform the following steps:
- Click on your username in the upper right-hand side of the homepage.
- Select "NuGet API Key" from the left-hand navigation window.
- Select "Reset API key"
- Enter your password
- Take note of the new API key
If you change your API key, you will need to change the key in the Jenkins jobs that are pre-configured for you. See the next section for information on how to connect to Jenkins.
Choco Apikey Command
To help make pushing packages easier, the choco apikey
command is available.
This will store your API key for a specific source as part of Chocolatey's configuration.
This will be encrypted. To setup, do the following:
:choco-info: NOTE
Please run the below from an administrative PowerShell session.
choco apikey add --key="'$YourApiKey'" --source="'https://chocoserver:8443/repository/ChocolateyInternal/'"
Step 7: Install and Configure Chocolatey On Clients
This script, like all of the others here would need to be run in an administrative PowerShell context. However, this one is run from your client machines and not the QDE.
Set-ExecutionPolicy RemoteSigned -Scope Process -Force; iex ((New-Object System.Net.WebClient).DownloadString('https://chocolatey.org/Import-QuickDeployCertificate.ps1')); Set-ExecutionPolicy RemoteSigned -Scope Process -Force; iex ((New-Object System.Net.WebClient).DownloadString('https://chocoserver:8443/repository/choco-install/ClientSetup.ps1'))
What does this do?
- Sets the execution policy for this script run to remote signed scripts. This is only in the scope of this process and not permanent.
- Imports the SSL Certificate from the Quick Deploy Environment.
:choco-info: NOTE
This is a signed script that is used to import a certificate. Due to how it works and security considerations, there are very few options allowed.
- Switches execution policy to bypass for the internal script. This is only in the scope of this process and not permanent.
- Calls Client setup script from the QDE environment (see below for what it does).
:choco-warning: WARNING
If your clients are airgapped or you have changed the hostname, you will need to find a different means to import the QDE Certificate. Please reach out to support for options.
:choco-warning: WARNING
If the QDE hostname has been changed, the above script most likely will fail.
You won't be able to use the above script, and you will need to host your own script somewhere that is trusted so that the QDE certificates can be trusted. Please see SSL/TLS Setup for options.
Please contact support if you need help here.
The ClientSetup.ps1 script will:
- Install Chocolatey
- License Chocolatey
- Install the licensed extension (without the PackageBuilder/Internalizer shims)
- Install the licensed agent
- Configure ChocolateyInternal source
- Configure Self-Service mode
- Configure Central Management check-in
Step 8: Turn On Package Internalization
Chocolatey For Business includes the Package Internalizer feature, which takes a package from the Community Repository and rewrites the package to include all the binaries necessary to complete the installation of the application. You'll find in the C:\choco-setup\files directory a script named Invoke-ChocolateyInternalizer.ps1
to help you with the process of internalizing additional packages into your environment.
The script accepts an array of Packages, your Local Nexus repository URL, the remote URL to look to for internalization, and your Nexus repository API key.
Example Usage:
. C:\choco-setup\files\Invoke-ChocolateyInternalizer.ps1 -Packages adobereader,vlc,vscode -RepositoryUrl https://chocoserver:8443/repository/ChocolateyTest/ -RemoteRepo https://chocolatey.org/api/v2 -LocalRepoApiKey [REDACTED_API_KEY]
:choco-info: NOTE
Please run the above from an administrative PowerShell session.
Step 9: License the QDE VM
This VM is running an UNACTIVATED Server 2019 Standard Operating System. If you plan to use this virtual machine long-term, you will need to apply a license to the VM. If you use a KMS server in your environment, and have it configured on clients via Group Policy, you likely have nothing to do here, but verify.
If you rely on Retail or MAK licensing, you will need to apply the license using the following, replacing the x's with your actual product key:
:choco-info: NOTE
Please run the below from an administrative PowerShell session.
slmgr.vbs /ipk xxxxx-xxxxx-xxxxx-xxxxx
Common Errors And Resolutions
Unable login to Jenkins website, after browsing to Nexus website
On the QDE VM, once you browse to the Nexus website at https://chocoserver:8443
, you will receive the following error when trying to browse to the Jenkins website at http://chocoserver:8080
:
This site can’t provide a secure connection
ERR_SSL_PROTOCOL_ERROR
This is due to the fact that Nexus has enforced an HSTS policy on the browser, blocking access to unsecured http:
addresses. This will be fixed in future versions of QDE. In the interim, you can bypass this limitation with the following steps:
- Add the following line to the file
C:\ProgramData\sonatype-work\nexus3\etc\nexus.properties
:
jetty.https.stsMaxAge=-1
- Close all instances and tabs of Chrome. Open Chrome again, so that only the one tab is open.
- Type
chrome://net-internals/#hsts
into the address bar to access the network internals page. - In the
Delete domain security policies
section near the bottom of the page, typeCHOCOSERVER
(or the hostname if you changed it) and press theDelete
button. - In the
Query HSTS/PKP domain
field, typeCHOCOSERVER
(or the hostname if you changed it) , and click theQuery
button to confirm that the output isNot found
(this means the HSTS settings have been removed). - Close all Chrome browser tabs and windows.
- Open up an Administrative PowerShell window, and use the following command to restart the Nexus service:
Restart-Service nexus
After the Nexus service has completed restarting, you should now be able to browse to the Jenkins website at http://chocoserver:8080
.
"Server Error" warning when resetting "admin" credential in Nexus
When attempting to reset the admin
account credential in Nexus, you receive a "Server Error" warning in the top right corner of the page, as shown below:
Though it may not be obvious, this is actually caused by Nexus not having enough disk space to function properly. We often see this occur if the Expand disk size
step from above was missed. Please confirm that you have completed the Step 1: Expand Disk Size step. Please keep in mind, this step is NOT the same as expanding the disk at the hypervisor level.
Context menu items for Package Builder and Package Uploader not available
xsWhen right-clicking an exe or msi file on QDE, you may notice that the context menu items for Package Builder are missing. As well, when right-clicking on a nupkg file, you may also see the Package Uploader context menu entry is missing. This feature can be controlled by passing a custom parameter when installing the Chocolatey Licensed Extension package, but can be restored to its default state quite simply.
Assuming the latest chocolatey.extension.nupkg
is in your C:\choco-setup\packages
folder, open up an Administrative PowerShell window and reinstall the Chocolatey Licensed Extension (and reset Explorer for your changes to take effect immediately):
choco upgrade chocolatey.extension -y --source="'C:\choco-setup\packages'"
Stop-Process -Name explorer -Force