---
title: Cycle CI Appliance Customer Setup Guidelines
description: Preparing your environment for the Cycle Appliance
---
[Skip to content](https://kb.cyclelabs.io/cycle-ci-appliance-customer-setup-guidelines#main-content)
English - United States
Show submenu for translations
Open main navigation
Close main navigation
- English - United States
Show submenu for translations
- [Get Support & Track Tickets](https://help.cyclelabs.io/)
[Get Support & Track Tickets](https://help.cyclelabs.io/?hsLang=en-us)
How can we help you?
- There are no suggestions because the search field is empty.
1. [Cycle Knowledge Base](https://kb.cyclelabs.io/?hsLang=en-us)
2. [Cycle Appliance and CI/CD](https://kb.cyclelabs.io/cycle-appliance-and-ci-cd?hsLang=en-us)
# Cycle CI Appliance Customer Setup Guidelines
Preliminary Prerequisites
1. 1. **Project Contact List** - A contact list of the project team that will participate from within your organization. Particularly important are the IT contacts who will be able to assist with networking configuration and troubleshooting.
2. **Dedicated Cycle Appliance Testing Instance** - A standalone instance of the your system under test that is dedicated to pipeline testing. Please provide all connection strings and user information for the environment.
3. **Test Instance Data Snapshotted and Restorable** - Confirm that sufficient data for the pipeline's test instance is snapshotted and can be restored. Data should adhere to the sufficiency standard outlined in the Cycle Customer Prerequisites document.
4. **Setup Version Control For Test Resources** - A Bitbucket or comparable version-controlled repository to hold all test resources.
5. **Configure VPN Resource** - In order to setup the VPN connection between Azure and the on-prem network, confirm that a compatible VPN device with Azure is configured.
- For more information about compatible VPN devices and device configuration, see [About VPN Device](https://docs.microsoft.com/en-us/azure/vpn-gateway/vpn-gateway-about-vpn-devices).
2. 6\. **Identify Reporting Needs** - Outline the expected reports to be provided on test executions. This would include any databases for logging to and any third party app integrations.
### Setup Processes
### 1) Create your Azure account
Use the existing Microsoft documentation for this [available here](https://docs.microsoft.com/en-us/learn/modules/create-an-azure-account/).
### 2) Install Jenkins in Azure
- Go to Azure marketplace, search for "**Jenkins**"
- Select the first option, make sure its the one by Microsoft
- Click **Create**
### You will need to complete information in each of the forms listed below to create your Jenkins instance.
### Basics:
- Subscription - your Azure account
- Resource group - create new resource group with a unique name for your CI Pipeline Build
- Region - East US 2
- Username - keep default
- Authentication type - SSH Public Key
- Generate this and save your public and private keys locally with an SSH keygen of your choosing and paste public key into Azure.
- PuTTY can be used to generate an SSH key. Instructions on using PuTTy to generate an SSH key can be found [here](https://www.ssh.com/ssh/putty/windows/puttygen).
### Additional Settings:
- VM disk type - SSD
- Keep defaults for: Virtual Network, Subset, Public IP
- Domain name label - choose a domain name for your pipeline here (ex: JenkinsDemo)
- Keep defaults for: Jenkins release type, JDK type
### Integration settings:
- Service Principal Integration: **Manual**
- In a new tab, open Azure portal and open Cloud Shell:
- In Cloud Shell, enter this command to create a service principal (you can use a different name than **JenkinsDemo** if preferred):
- ```
az ad sp create-for-rbac --name JenkinsDemo
```
- **Copy the whole resulting chunk into a local text file, you will need it for a few things. Looks like this:**
****
- Paste the **appId** into corresponding field in Integration Settings.
- Paste the **Password** into **Secret** field in Integration Settings.
- Enable Cloud Agents - VM
- Enable Azure Native Artifice Manager - no
- You can exit cloud shell in the other tab
### Review and Create
- **FYI - this will create resources that cost real money so you want approval to run this.**
- **After you receive the Validation Passed message, click Create. If your validation does not pass, then review the Basics, Additional Settings, and Integration Settings to ensure all of the appropriate fields are populated.**
- Deployment takes around 10-15 mins
### Connect to Jenkins VM Locally
- When complete, check the Azure resource group, make sure Jenkins (along with its dependencies) is there by clicking "Go to Resource Group"
- Click on the "**jenkins**" Virtual Machine (top choice in list)
- Copy **DNS name** field and paste into new tab, you should see **Jenkins On Azure** splash page:
- **NOTE The following steps can be followed if you are doing this work on a Mac. Using PuTTY is a better option when using a Windows computer. I had issues with the powershell SSH command accepting my private key**
- Here you can get the command to create your SSH tunnel:
ssh -L 127.0.0.1:8080:localhost:8080 username@jenkinspipelinetest.eastus2.cloudapp.azure.com
- Run this command in Windows PowerShell locally replacing the **username@** with your own Azure user.
**To open the SSH connection using Putty.**
- Create a new PuTTY SSH session.
- On the Session screen:
- Host Name (replace username and DNS name): [username@jenkinspipelinetest.eastus2.cloudapp.azure.com](mailto:username@jenkinspipelinetest.eastus2.cloudapp.azure.com)
- Connection Type SSH
- Port 22
- On the Connection -\> SSH -\> Auth screen, browse to the location of the private key you saved earlier
- 
- ON the Connection -\> SSH -\> Tunnels screen, Add a new forwarded port, Source 8080, Destination localhost:8080
- 
- Go Back to the Session screen, be sure to name your session and save it for future use
- After saving, load the session and click Open. You will be prompted for your key passphrase if you added one when you created the key unless you have added the key to Pageant
- If you are successfully connected, you should be at an open shell on the Jenkins machine. You will need to have this SSH connection open in order to interact with Jenkins at localhost:8080
- If you did this correctly, you should be able to open **localhost:8080** in your browser and you will see the Unlock Jenkins splash screen:
- Use the path provided here to get the initial admin password and paste it into the browser, click **Continue.**
- **You can run the following command in the open putty SSH connection to get the initial admin password**
- sudo -u root cat /var/lib/jenkins/secrets/initialAdminPassword
- Copy the password from your PuTTY session and paste it into the browser
- On the Customize Jenkins screen, choose **Install Suggested Plugins.**
### Create first admin user
- Use your own name and email etc. for new Admin User; Save and Continue
- Click **Start Using Jenkins**
### 3) Configure Jenkins
### Install Plugins
- When our own Azure marketplace offering is live, it will contain all of the necessary plugins already
- For POC we used the MS Jenkins offering
- Go to **Manage Jenkins \> Manage Plugins \> Installed** tab
- Verify the following plugins are installed:
- Azure VM Agents - azure-vm-agents:1.4.0
- Azure Container Agents - azure-container-agents:1.1.1
- Windows Azure Storage - windows-azure-storage:1.1.5
- Azure Credentials - azure-credentials:2.0.1
- Azure Container Service - azure-acs:1.0.1
- Cloud Statistics - cloud-stats:0.25
- Blue Ocean - blueocean:1.22.0
- Configuration as Code - configuration-as-code:1.36
- (Microsoft offering includes all the Azure plugins)
- If adding any, click "Download now and install after restart"
- Check "Restart Jenkins when installation is complete..."
### Configure System
- After plugins are installed, go to **Manage Jenkins** \> **Configure System**
- Scroll down to **Cloud** section
- If you are using the Microsoft Jenkins Azure offering:
- **Cloud Name** and **Azure Credentials** should be populated already
- **Resource Group Name** should also already have a populated list of resource groups
- If you are using the Tryon Jenkins Azure offering you will need to Add the Azure credentials here
- **Domain** - Global credentials
- **Kind**- Microsoft Azure Service Principal
- **Scope** - Global
- **Subscription ID** - copy from Azure Service Provider page
- **Client ID** - appID saved from earlier
- **Client Secret** - password saved from earlier
- **Tenant ID** - tenant saved from earlier
- **ID** - Chose a name for this, something like "JenkinsAzureSP" (no spaces allowed)
- **Description** - Up to you, spaces allowed
- Click **Add**
- Reference to "copied info from earlier":
****
- Once added, existing resource groups should show up
- **Resource Group Name** - use the resource group you set up for this
### Add Azure Virtual Machine Template
- **Name** - ubuntu-az
- **Description** - Ubuntu based nodes for pipeline testing
- **Labels** - ubuntu-az
- **Region** - East US 2
- **Virtual Machine Size** - Standard\_D2\_v3
- **Storage Account Name** - Create New...
- **Retention Strategy** - Azure VM Idle Retention Strategy
- **Usage** - Only build jobs with label expressions matching this node
- **Image Configuration** - Use Built-In Image Ubuntu 16.04 LTS
- **Pre-installed Tools** - Install Git, Install Docker
- Should look like this:
- Verify template
- Save
### 4) Clone the CI Appliance Repository
- **NOTE: For this, I downloaded Ryan's repository, created a new repository, and then added his files to my new repository rather than cloning straight from his repo.**
- **Repo to clone**: https://bitbucket.org/ryanbergertryon/vttest-ryan/src/master/
- Give it a name and clone
- After cloning this repo, you will need to update the Jenkinsfile to match your new Repository name:
1. In the root of the Repository directory, edit the **Jenkinsfile** in your IDE of choice
2. Update lines **35** and **65** to reference your Repository name (keep the **\_master**). Example is shown below:
3. `sh '''cd /home/agentadmin/workspace/``your-repository-name``_master/docker`
4. `docker run --net docker_default -v /home/agentadmin/workspace/``your-repository-name``__master:/home/cycle briantryon/cycle:2.6.0-alpha5 --settings ProduceLocalReport=true -o /home/cycle/reports -p /home/cycle features/web_test.feature features/ssh/SSH_11_vt220.feature'''`
5. Commit and push these changes up to your remote Repository
### 5) Deploy the new Pipeline to your Jenkins build
- Now that we have our own repo updated, we go back into Jenkins and click **Open Blue Ocean** on the top left
- Click Login in top right corner
- Where do you store your code? Select the host of your cloned repo.
- Log into bitbucket/github etc. (If you have an app password for bitbucket, use that here)
- Select the appropriate repo from list of available repos
- Click Create Pipeline
- Jenkins file in repo will tell Jenkins what to do and will run the pipeline from there!
- [Getting started](https://kb.cyclelabs.io/getting-started?hsLang=en-us)
- [Using Cycle with BYWMS](https://kb.cyclelabs.io/using-cycle-with-bywms?hsLang=en-us)
- [Cycle Appliance and CI/CD](https://kb.cyclelabs.io/cycle-appliance-and-ci-cd?hsLang=en-us)
- [Tips and Tricks](https://kb.cyclelabs.io/tips-and-tricks?hsLang=en-us)
- [Native App](https://kb.cyclelabs.io/native-app?hsLang=en-us)
- [Deprecated Steps](https://kb.cyclelabs.io/deprecated-steps?hsLang=en-us)
- [Common Issues](https://kb.cyclelabs.io/common-issues?hsLang=en-us)
[](http://cyclelabs.io)
[mailto:email@email.com](mailto:email@email.com)
Copyright © 2026, Cycle Labs