Quick Deployment Environment Setup

📝 NOTE

This document is for Version 2 of the Quick Deployment Environment.
If you're using an older version of QDE, please refer to the QDEv1 Setup page.

This document contains instructions for importing the QuickDeploy appliance/VM, or creating a VM and attaching the QuickDeploy disk image to it.
You will receive a download link via email for an archive of the VM image.
Once you have this downloaded, it will be ready for extraction and import into your environment.

⚠️ WARNING

Please follow these steps in exact order.
These will be very important later when you are trying to use the environment.


Step 0: Setup Considerations

Keep the following points in mind during initial setup:

  • You will need access to AWS to download the VM image (specifically s3.amazonaws.com).
  • Hostname/FQDN changes made after setup will invalidate all scripts and certificates.
    Thus, if you plan to change the hostname, you must do so prior to running any setup scripts.
    If you run into issues, refer to the README file on the desktop of the VM.
  • Self-signed certificates are generated by default.
    If you plan to use your own certificates, pay special attention to the setup instructions in the provided README.
  • The back-end database is configured with no outbound connections.
    If you plan to change this, please reach out to Support for assistance.

Step 0.1: Changing the Hostname

⚠️ WARNING

Renaming the QDE host needs to be completed prior to ANYTHING that is done on the QDE box.
It is recommended to use the default hostname unless you really need to change it.

Please contact support if you run into issues.

If you rename the QDE Environment after running the initial setup scripts, there are some additional changes you'll need to make:

  1. Update client setup scripts that are initialized to the current QDE hostname during setup.
    You will need to go through the existing scripts in C:/choco-setup/files and replace the default -Hostname value of ALL scripts that have it.
    Please contact Support if you're unsure how to proceed here.
  2. Upload the ClientSetup.ps1 and ChocolateyInstall.ps1 to the Nexus repository.
  3. Replace the IIS-hosted Import-ChocoServerCertificate.ps1 script using the New-IISCertificateHost.ps1 script.
  4. Deploy the new certificate to all clients.
    See the Client Setup documentation for instructions on how to do this.
  5. There may be additional places impacted
    Check with support if you need confirmation.

Step 1: Import the Virtual Environment

Choose one of the following methods for what your hypervisor environment supports.

Platform: Azure

If you choose to use the scripts provided inside the 7zip archive, there are a number of pre-requisites you'll need to have already.

Prerequisites

📝 Note
Note that having both the Az and AzureRm PowerShell modules installed side by side is not supported.
You can see if you have AzureRm installed by running Get-Module -Name AzureRm -ListAvailable.
If there is no output, it is not installed.

  • Hyper-V PowerShell Module
    • For Windows 10 run Enable-WindowsOptionalFeature -Online -FeatureName Microsoft-Hyper-V-Management-PowerShell from an elevated PowerShell prompt.
    • For Windows Server 2012 and later, run Install-WindowsFeature -Name Hyper-V-PowerShell from an elevated PowerShell prompt.
  • Az PowerShell Module — To find out if you have the module installed run Get-Module -Name az -ListAvailable from an elevated PowerShell session.
    • To install the Az module using Chocolatey, run choco install az.powershell -y.
    • To install via PowerShell from the PSRepository, run Install-Module -Name Az -AllowClobber -Scope CurrentUser.
  • Either PowerShell 5.1 with .NET Framework 4.7.2 or PowerShell Core (required for the Az module).
    • PowerShell 5.1 and .NET 4.7.2
      • You can find out the current version of PowerShell you are running using the command $PSVersionTable.PSVersion from a PowerShell session.
      • To install PowerShell 5.1, either use choco install powershell -y to install with Chocolatey, or see Microsoft Docs.
      • To install .NET 4.7.2, either use choco install dotnet4.7.2 -y to install with Chocolatey, or see the Microsoft docs.
    • PowerShell Core
      • To install PowerShell Core, you can use choco install powershell-core -y to install with Chocolatey, or see the Microsoft Docs.
  • AzCopy v10 or later - this is needed in order to copy the disk to Azure.
    To find out if you have azcopy installed and which version, run azcopy --version.
    • To install AzCopy v10 or later, using Chocolatey run choco install azcopy10 -y or see the Microsoft Docs.

📝 Note

The scripts provided with the QDE virtual machine disk image have defaults that you need to ensure you are comfortable with and extensive help.
You can see the help, and the default, by running Get-Help <SCRIPT-NAME> -full.

These scripts will create resources in Azure which will cost you real money.
Please ensure you are comfortable with this before continuing.
See above to get help with the scripts.

Your execution policy must allow running scripts.
If it does not, you can set it for the current PowerShell session by running Set-ExecutionPolicy -ExecutionPolicy Bypass -Scope Process.
Any code or scripts must be run in an elevated PowerShell session.

Steps to create a QDE virtual machine in Azure:

  1. Download the Zip archive containing the Azure virtual machine disk (VHD), and unzip it to the directory you wish to store it in.
    You should have three files:
    • QuickDeployEnvironment-Azure.vhd
    • Set-QDEAzureDisk.ps1
    • New-QDEAzureVM.ps1
  2. While the scripts will do the majority of the hard work needed to create a QDE virtual machine in Azure, we do need to setup a resource group.
    The default resource group that the scripts will use is qdeserver-resgrp; if you prefer, you can supply an existing resource group using the -ResourceGroupName <YOUR-RESOURCEGROUPNAME> parameter.
    To create a resource group run New-AzResourceGroup -Name <RESOURCEGROUPNAME> -Location <YOUR-AZURE-LOCATION>.
  3. We need convert the disk you have downloaded to the size required, and then upload it to Azure so we can attach it to the QDE virtual machine we will create in the following steps.
    Note that the script we are about to run contains defaults that should work for the majority of users.
    However, please run Get-Help Set-QDEAzureDisk.ps1 -Full to get help on the parameters you can provide and the defaults that have been set.
    Once you are comfortable, in the directory you extracted the files to, run .\Set-QDEAzureDisk.ps1 -Verbose <PARAMETERS> (where <PARAMETERS> is any additional parameters you want to provide).
    Providing the -Verbose switch produces output on the screen.
    Note that the processes of converting the disk and uploading it can take a long time.
  4. Before we connect to the QDE virtual machine in Azure we must reset the password.
    To create a password we can provide to the next script, run $qdePwd = '<YOUR-PASSWORD> | ConvertTo-SecureString -AsPlainText -Force (where <YOUR-PASSWORD> is the password you want to set and is longer than 12 characters).
  5. Once the disk has been uploaded, we need to create the QDE virtual machine in Azure and attach the disk we uploaded as the operating system disk.
    Note that the script we are about to run contains defaults that should work for the majority of users.
    However, please run Get-Help New-QDEAzureVM.ps1 -full to get help on the parameters you can provide and the defaults that have been set.
    Once you are comfortable, in the directory you extracted the files to, run .\New-QDEAzureVM.ps1 -Verbose -AdministratorComplexPassword $qdePwd <PARAMETERS> (where <PARAMETERS> is any parameters you want to provide and $qdePwd is the password we created in the previous step).
    You can provide the -Verbose switch to display a summary of actions being taken.
  6. Once this is complete the script will output the command you can run to connect to the virtual machine, including the IP address (if you are using the -Verbose switch).
    Use mstsc.exe /v:<IP-ADDRESS> to connect and login with the password you created in a previous step.

Platform: Hyper-V

📝 Note

Windows 10 and Windows Server 2016/2019 version of Hyper-V now come with built-in support for Hyper-V Integration Services, so they automatically get pushed to guest VMs.
In older versions of Hyper-V, you should see an option to Insert Integration Services Setup Disk.
You can use this option to install and enable Hyper-V Integration Services.

Hyper-V Appliance

  1. Download zip archive containing the Hyper-V VM directory structure, and unzip it to the directory you wish to store it in.

  2. Open Hyper-V Manager, and select Import Virtual Machine from the right sidebar (or Action menu), and choose the folder you extracted from the above archive (e.g. ChocoServer).

  3. Increase the size of the VHD, for example, to 500GB.
    Increase to what you feel comfortable with, keeping in mind QDE is in part a repository server, and will require a fair amount of space to operate for any length of time if you're utilizing that.

    # This only increases the available size of the image.
    # You will still need to increase the allocated space for the C drive when you start the VM.
    Resize-VHD -Path C:\path\to\QuickDeploy Environment.vhd -Size 500GB
    
Cick to show animated summary

QDE Hyper-V Appliance Import

Hyper-V VHD

  1. Download the VHD from provided link, and unzip it to the directory you wish to store it in.

  2. Increase the size of the VHD, for example, to 500GB.
    Increase to what you feel comfortable with, keeping in mind QDE is in part a repository server, and will require a fair amount of space to operate for any length of time if you're utilizing that.

    # This only increases the available size of the image.
    # You will still need to increase the allocated space for the C drive when you start the VM.
    Resize-VHD -Path C:\path\to\QuickDeploy Environment.vhd -Size 500GB
    
  3. Open Hyper-V Manager.

  4. Create a new VM.

  5. If prompted, choose a Generation 1 virtual machine.

  6. Set startup memory to 8192 MB (you can change this later if you need to).

  7. When asked to create a new disk or use an existing one, select Use existing virtual disk and browse to the VHD you unzipped in Step 1.

  8. Adjust the hardware specifications of the VM.
    For a performant system, the following are recommended:

    • 4 vCPUs
    • 8 GB RAM
Cick to show animated summary

QDE Hyper-V VHD

Platform: VMware / Other (OVF/OVA Template)

  1. Download either the OVF or OVA from the provided link, and unzip to the directory you'd like to store it.
  2. Import the template into your hypervisor of choice.
    You can typically directly import the OVA or OVF template file, and most settings should be pre-configured for you.
    • Instructions on doing this for VMware are here.
  3. Once the import completes, go into the VM's hardware settings and expand the main disk to at least 500GB.
  4. Boot up the VM, and (if needed) install any software required / recommended for your hypervisor.

Platform: VMware (VMDK file)

  1. Download VMDK from provided link, and unzip it to the directory you wish to store it.
  2. For ESX/ESXi, open vSphere and upload the downloaded VMDK to your datastore.
  3. Create a new VM.
  4. When prompted for OS type, choose Windows Server 2019 (if available), or Windows Server 2016 or later.
  5. If prompted for boot firmware, choose Legacy BIOS (not UEFI).
  6. When asked to create a new disk or attach, delete the default disk, select attach, and browse to the VMDK you uploaded. IMPORTANT: [vCenter/ESX/ESXi] You must select an IDE controller under the "Controller Location" setting of the disk. If you leave the controller as SCSI (default), your VM will not boot.
  7. Adjust the hardware specifications of the VM. For a performant system, the following are recommended:
    • 4 vCPUs
    • 8 GB RAM
  8. Once you click Finish, go back into the Edit settings context menu for the VM, and expand the disk you attached to 500GB (double-check in OS, and extend if needed). NOTE: likely you will need to allocate the additional space to the C drive.
  9. Boot up VM, and Install VMware Tools using the console menus (this will require a reboot).
Click to show animated summary (ESX/i)

QDE VMware VMDK

Click to show animated summary (VMware Fusion, OSX)

QDE VMware VMDK

Platform: Other

If your hypervisor supports importing from an OVA or OVF, you should be able to import that image in most cases.
Otherwise, or if you run into issues doing that, we recommend downloading the VMDK file and converting it to a format supported by your hypervisor.

Please ensure you know what you're doing before attempting this.
We can only support the hypervisors listed here, and will not be able to provide assistance in conversion and ensuring the QDE image works in your environment.
However, once you have the image running in your hypervisor, our support team will be happy to assist you however they can.


Step 2: Other Considerations

Step 2.1: DNS Settings

The QDE environment is configured by default to use DHCP for easier initial setup.
You will likely need to reconfigure it with a static IP address depending on your organization's policies.


Step 3: Virtual Environment Setup

⚠️ Warning

If you have an existing corporate environment you will be servicing with the QDE VM, be sure to perform your organization-specific initial configuration before running setup scripts.

Step 3.1: Expand Disk Size

On the machine, please check the size of the C drive.
If the volume needs to be expanded, expand it to the space you've allocated for the machine by running this command in an administrative PowerShell console:

# This should increase the space available on the C drive to the maximum available size.
Resize-Partition -DriveLetter C -Size ((Get-PartitionSupportedSize -DriveLetter C).SizeMax)

Alternatively, you can use the Disk Management utility to expand the disk, if you prefer.

Step 3.2: Add Chocolatey License File

In the Quick Deployment Desktop Readme, you will be instructed to copy your chocolatey.license.xml to the VM.
You should already have been given a license file prior to downloading QDE.
We generally recommend you copy the file into the VM directly, if possible.

⚠️ Warning

If you find that you need to copy the file contents in order to get the license file text into a new file in QDE, the file format and name is extremely important to get right.
If you don't save the file in UTF-8 encoding or there is extra whitespace, Chocolatey will consider it invalid.

Please contact support if you need help here.

Step 3.3: Follow README instructions to finish environment setup

On the desktop of your QDE VM, there is a Readme.html file, that will guide you through the rest of the setup process once you are logged in.
A version of this readme file can be found in the Quick Deployment Desktop Readme.

📝 Note

The online version 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 online, prefer the online version.

Step 3.4: Database Password Changes (Optional)

The database credentials are currently pre-set.
If you would like to change the credentials associated with the database, you will need to follow these steps.

  1. Change the database access credentials

  2. Reinstall the chocolatey-management-service package

    choco uninstall chocolatey-management-service -y
    choco install chocolatey-management-service -y --package-parameters-sensitive="'/ConnectionString=""Server=localhost\SQLEXPRESS;Database=ChocolateyManagement;User ID=ChocoUser;Password=NewPassword;""'"
    
  3. Reinstall the chocolatey-management-web package

    choco uninstall chocolatey-management-web -y
    Choco install chocolatey-management-web -y --package-parameters-sensitive="'/ConnectionString=""Server=Localhost\SQLEXPRESS;Database=ChocolateyManagement;User ID=ChocoUser;Password=NewPassword;""'"
    

Step 4: Firewall Changes

See QDE Firewall Changes.


Step 5: Install and Configure Chocolatey on Clients

See QDE Client Setup.


FAQ

How do I upgrade QDE?

While we will continue to make improvements to the QDE, there is no upgrade path for the Virtual Machine itself.
You can choose to start over with a newer version, but that would mean going through the entire setup process from the beginning once again.

Instead, it is much easier to upgrade the components individually, and that is how we recommend upgrading aspects of QDE.
Should you want to upgrade say Central Management, you can follow the Central Management steps for upgrade at Upgrade Central Management.

Should I upgrade Jenkins?

The Jenkins package in QDE is pinned at version 2.222.4; this is the latest version we have currently tested.
An upgrade is possible, however we recommend you approach this with caution for the time being.
Upgrading to a newer version via the typical Jenkins installer package requires some additional work due to the way Jenkins handles upgrades with their installer.

Upgrading through the Web UI

Upgrading through the Web UI is the simpler way to go, and doesn't seem to carry any of the complications that can arise when upgrading via their MSI installer.
When an upgrade is available, Jenkins will show a new notification that looks like this when clicked:

Jenkins upgrade notification, showing the notification message prompting to upgrade

To upgrade via the web UI:

  1. Login to Jenkins
  2. Click the 🔔 notifications bell
  3. Select Or Upgrade Automaticallynot the download link
  4. When you are taken to the Installing Plugins/Upgrades screen, check the Restart Jenkins when installation is complete and no jobs are running checkbox
  5. Once Jenkins indicates the process is complete and has restarted, log back in

If you would like to upgrade Jenkins to a newer version using the installer, please refer to Jenkins' Upgrade Guide.
Some or all of the complexities in the upgrade process will likely be made automatic in the Chocolatey package as we're able to test and verify that the upgrade path works.
Until then, approach with caution and follow the Jenkins documentation closely when attempting an upgrade.


Quick Deployment Environment