This is an overview of the Chocolatey for Business Ansible Environment.
It is a playbook and selection of modules, allowing for the speedy creation of an opinionated, pre-configured environment containing Chocolatey Central Management (CCM), a package repository (Sonatype Nexus Repository), and an automation engine (Jenkins).
A Chocolatey for Business Ansible Environment is a fully functional Chocolatey for Business environment; as such, it will require a business or trial license.
To deploy the Chocolatey for Business Ansible Environment you will need:
- A Chocolatey for Business license, or Trial license.
- One or more existing server accessible from your Ansible host.
- The ability to create a CNAME DNS record for your chosen FQDN.
- A valid certificate for your chosen FQDN, in PFX format, with exportable private key.
For portions of this guide using Ansible, we will assume that you either have an Ansible Execution Environment preconfigured, or are using the dev container to execute the playbooks. You should have the latest supported version of the Chocolatey.Chocolatey Ansible collection installed, along with any additional prerequisites listed in the requirements.txt.
You can install the Python requirements for the module using
pip3 install --upgrade -r /requirements.txt
Deploying the Chocolatey for Business Ansible Environment
The Chocolatey for Business Ansible Environment is designed to deploy Chocolatey Central Management and all the suggested softwares to one or more servers within your environment, and provide methods for deploying Chocolatey for Business to your other endpoints.
You can deploy this using Ansible Automation Platform, an existing installation of the Ansible client, or the dev container image provided within the repository (as well as a variety of other methods).
This guide will be written as if you were using Ansible from a local installation or the dev container, but can be easily adapted to run from Automation Platform / AWX.
If you want to run this deployment on an environment that doesn't have access to the internet, refer to the offline deployment page and start on a Windows machine.
Clone or otherwise download the
c4b-ansible repository from GitHub.
git clone https://github.com/chocolatey/c4b-ansible.git
Configuring Your Hosts
You can deploy the Chocolatey for Business Ansible Environment to one or more servers. There are four services being installed:
- Chocolatey Central Management
- Sonatype Nexus Repository
- Optional: SQL Server Express
Installing On a Single Host
To install on a single host, create a host with the title
ccm_server. All services will be installed to this host. There is an example of a hosts file containing a single host in the root of the repository - hosts.yml.
all: hosts: ccm_server: ansible_connection: winrm ansible_winrm_transport: ntlm ansible_port: 5986 ansible_winrm_scheme: https ansible_host: chocoserver ansible_user: ansibleuser ansible_password: !vault | $ANSIBLE_VAULT;1.1;AES256 [...]
Installing On Multiple Hosts
To install on multiple hosts, define hosts with the following names:
ccm_server: Chocolatey Central Management service and website
nexus_server: Sonatype Nexus Repository
database_server: SQL Server Express
all: vars: ansible_connection: winrm ansible_winrm_transport: ntlm ansible_port: 5986 ansible_winrm_scheme: https ansible_user: ansibleuser ansible_password: !vault | $ANSIBLE_VAULT;1.1;AES256 [...] hosts: ccm_server: ansible_host: chocoserver nexus_server: ansible_host: nexus jenkins_server: ansible_host: chocorunner database_server: ansible_host: db1
If any are not defined, the service will be installed on the
If a connection string is passed, we assume the database is set up and do not install SQL Server.
Using An Existing Database
You can provide a connection string to the environment to use for storing Chocolatey Central Management data. This can have significant benefits for performance, as well as simplifying backups and load-balancing of instances.
To use an existing database server you wish to use, follow the instructions for creating a database and provide the connection string as a variable.
Secrets, including credentials, for the various services will be generated during the deployment. They are stored temporarily in the
/credentials directory within the repository, and you should store and remove them from this when the deployment is complete.
If you would prefer to create and maintain them from scratch, you can modify the values of the following secrets within the
ccm_password: !vault | $ANSIBLE_VAULT;1.1;AES256 [...] ccm_client_salt: !vault | $ANSIBLE_VAULT;1.1;AES256 [...] ccm_service_salt: !vault | $ANSIBLE_VAULT;1.1;AES256 [...] ccm_encryption_password: !vault | $ANSIBLE_VAULT;1.1;AES256 [...]
We have shown examples of redacted secrets being stored securely using Ansible Vault throughout this document. They will need to be replaced with your secrets, and we'd recommend you store them securely!
You can select packages to directly internalize at the end of the deployment from the Chocolatey Community Repository.
To do so, uncomment the example array
internalize_packages in the
/group_vars/all.yml, and add packages that you wish to be internalized.
# Packages to Internalize internalize_packages: - 1password - 7zip - adobereader - azcopy - azure-cli - firefox - git - notepadplusplus - powershell - slack - vscode
This will result in packages matching the ID's being internalized from the Chocolatey Community Repository.
Deploying the Environment
You can now run the playbook using
ansible-playbook. If you have modified the hosts file in the base of the repository, you can run it as follows:
ansible-playbook ./c4b-environment.yml -i ./hosts.yml
The playbook will prompt you for the location of your license, certificate, and password. After you have answered these prompts, the playbook will deploy all of the services.
You can add the values to an inventory file or the playbook directly, instead of being prompted at runtime.
Configuring Chocolatey Central Management
You cannot create users in Chocolatey Central Management until you have configured an SMTP server. To do this, please see how to configure SMTP. You can log in to Chocolatey Central Management using the credentials provided in the credentials document (see Accessing Services, below).
At this point, the Chocolatey for Business Ansible Environment should be deployed with the following accessible services:
|Chocolatey Central Management||ccmadmin|
|Sonatype Nexus Repository||admin|
Passwords to login to the services have been stored in the credentials directory within the root of the
There should be a
CCM.html file that contains a start-up guide, including initial steps and credentials for the various services. You should secure this appropriately.
You will need an SSL certificate for the domain you intend to use. This certificate:
- Needs to be in the PFX format.
- Needs to include an exportable Private Key.
- Must have a password.
You can either provide a self-signed SSL certificate, or a purchased or acquired certificate from a Certificate Authority (CA).
Self-Signed SSL Certificates
You can quickly generate a self-signed certificate on any recent Windows machine, using PowerShell.
- Open an elevated PowerShell console
- Run code similar to the following, modifying the
$Domain = Read-Host "Enter the FQDN you plan to use to access the Chocolatey for Business Ansible Environment sites" $Password = Read-Host "Enter a password to use for the PFX" -AsSecureString $Cert = New-SelfSignedCertificate -DnsName $Domain -CertStoreLocation cert:\LocalMachine\My $Cert | Export-PfxCertificate -FilePath ~\Desktop\$($Domain).pfx -Password $Password
You can then use this generated file and the password you set to deploy your Chocolatey for Business Ansible Environment.
Your browser will display warnings when accessing the Chocolatey for Business Ansible Environment sites with a self-signed certificate. To stop these warnings, you need to import this certificate to the
Trusted Root Certification Authoritiesstore on any clients used to access the services. Unless you know what you're doing, we would strongly recommend using a certificate from a CA like LetsEncrypt.
Purchased/Acquired Certificates From a Certificate Authority
Organizations can also opt to purchase or acquire a certificate from an external Certificate Authority (e.g. LetsEncrypt). As mentioned before, you will need to ensure that the "Subject/Common Name" attribute on the SSL certificates matches the FQDN you are using. If you have a preferred vendor for certificates, you should refer to their documentation for best practices in acquiring a certificate.
Common Errors and Resolutions
SQL Installation Stalling
We have seen the SQL Server installation fail with code
-2068774911, or hang indefinitely when the target server only has IPv6 DNS.
This can be resolved by a login to the server using RDP and re-running the playbook, or by ensuring the target server has IPv4 DNS available.
Timeout When Downloading Jenkins Plugins
Sometimes the downloading of Jenkins plugins times out. Rerunning the playbook again should complete this.