Aerogear Guides Tutorials to help get you off and running.

Digger installation guide

AeroGear Digger Installation

The AeroGear Digger project allows you to setup a Jenkins CI/CD server that utilizes Jenkins Pipelines for mobile application building. AeroGear Digger is deployed in OpenShift containers, providing isolated build environments.

aerogear-digger-installer - GitHub repo with an Ansible based tool, used for automated AeroGear Digger installation.

For more details about Ansible playbooks and variables, please refer to Ansible Playbook Variables Docs.

Use the installation tool to create an OpenShift project and to deploy the following components in it:

  • A Jenkins server, used to run the build tasks

  • Docker-formatted images with all tools required for Android application building

  • A Nagios server for health monitoring of installed components

If you want iOS building capability, the installer can optionally configure macOS server(s) with required tools. See Setup macOS Servers (optional). These are not deployed in OpenShift project, but are connected as a Jenkins slaves to Jenkins master present in OpenShift project.

If you choose to use macOS servers, their manual pre-configuration is required, see macOS Prerequisites (optional)

Installing AeroGear Digger Behind Proxy

It is possible to deploy Digger behind HTTP/HTTPS proxy that do not require authentication. see Using HTTP/HTTPS Proxy with Aerogear Digger (optional)

Sample jenkinsfiles To Utilise Jenkins Pipelines

A suite of sample jenkinsfiles used for demonstration of application building using Jenkins pipeline is available in aerogear-digger GitHub repo.

Prerequisites

Before running the Digger installer, please make sure the following prerequisites are met:

Proxy Configuration (optional)

Ansible 2.2.3 or higher

Digger Installer requires a version of Ansible 2.2.3 or higher to be installed on node which will execute the Ansible playbook. You can check the installed Ansible version by running ansible --version. Please refer to Ansible installation instructions.

Access to Internet

Digger requires an outbound Internet access to perform npm installations. Make sure that all relevant nodes/servers have outbound Internet access.

Java 2.2 and higher

Java is required for Jenkins configuration during the installation. Will be automatically installed if not present.

OpenShift 3.3 or higher

  • An OpenShift Container Platform, and its command line tool (oc) installed locally.

  • OpenShift cluster with the following PVs (Persistent Volumes) available:

    • 40GB for Jenkins

    • 10GB for Android-sdk

    • 1GB for Nagios

Access to DockerHub

The installer retrieves the Docker-formatted images from https://hub.docker.com/. Please make sure that all nodes in the OpenShift Installation have access to this site.

macOS Prerequisites (optional)

Completing the steps presented in this section are only required to provision a macOS server to enable iOS app building with Aerogear Digger. Please skip to Run Digger Installer if you don’t need this functionality.
  • A fresh macOS 10.12 Sierra install (MacinCloud service can be used, too)

  • 4GB RAM

  • 2 CPU Cores

  • 30GB minimum disk space and and additional 20GB per installed XCode version

macOS Configuration Requirements

  1. Ansible requires SSH sudo access to the macOS server in order to correctly provision the server to support iOS builds.

    Enable SSH connection by following these steps:

  2. Provide macOS server with Internet access to list of hosts

Create a sudo macOS User

Create a user with sudo permissions and SSH access on the macOS server.

An example bash script is provided.

Review the script before using it. The unmodified script will allow access to your machine with a default password. Change the default PASSWORD and ensure that USER_ID is unassigned.

By default, the script will create a user named jenkins with USER_ID=550 and add the user to the the sudoers file. The user’s PASSWORD is set by default to Password1. The user is added to the admin group.

Restart the server to implement the changes.

Download and execute the script with the following commands:

curl -O https://raw.githubusercontent.com/aerogear/aerogear-digger/master/admin/create-osx-user.sh
sudo bash create-osx-user.sh
#!/usr/bin/env bash

USERNAME="jenkins"
PASSWORD="Password1"
REAL_NAME="Jenkins Agent"
GROUP_NAME="staff"

# the first user's id is 500, second is 501 ...
# picking a big number to be on the safe side.
# You can run this one to list UIDs
#   dscl . -list /Users UniqueID
USER_ID=550

# GID 20 is `staff`
GROUP_ID=20

############### end of parameters

. /etc/rc.common
dscl . create /Users/${USERNAME}
dscl . create /Users/${USERNAME} RealName ${REAL_NAME}
dscl . passwd /Users/${USERNAME} ${PASSWORD}

dscl . create /Users/${USERNAME} UniqueID ${USER_ID}
dscl . create /Users/${USERNAME} PrimaryGroupID ${GROUP_ID}
dscl . create /Users/${USERNAME} UserShell /bin/bash
dscl . create /Users/${USERNAME} NFSHomeDirectory /Users/${USERNAME}
dseditgroup -o edit -a ${USERNAME} -t user admin
cp -R /System/Library/User\ Template/English.lproj /Users/${USERNAME}
chown -R ${USERNAME}:${GROUP_NAME} /Users/${USERNAME}

echo "${USERNAME}  ALL=(ALL:ALL) ALL" >> /etc/sudoers

echo "Done creating OSX user - you may need to restart the osx server to apply all changes for the user ${USERNAME}"

Configure Remote Login(SSH) in Ansible Host

Enable the remotely running Ansible process to execute commands on the macOS server via SSH.

A sample script is provided below. The USERNAME variable should contain the name of the macOS user created in the previous step. This allows the USERNAME to access the server via SSH with a password.

Review and understand the script before using it.

You can also add a public encryption key to the authorized_keys file associated with the user. Private key of the asymmetric key pair is stored on the Ansible management node.

The script can be downloaded and executed using the following commands:

curl -O https://raw.githubusercontent.com/aerogear/aerogear-digger/master/admin/enable-osx-remote-login.sh
sudo bash enable-osx-remote-login.sh
#!/usr/bin/env bash

# This script helps with enabling SSH for given OSX user.
# This script is not meant to be run in an automation. Run it manually.

USERNAME="jenkins"

# com.apple.access_ssh is a special group name on OSX.
# any user part of that group can have SSH connections in.
OSX_SSH_GROUP_NAME="com.apple.access_ssh"

systemsetup -setremotelogin on
# in order to check what groups are are there:
#   dscl . list /Groups PrimaryGroupID
# create a group for limiting SSH access
dseditgroup -o create -q ${OSX_SSH_GROUP_NAME}
# add user into this group
dseditgroup -o edit -a ${USERNAME} -t user ${OSX_SSH_GROUP_NAME}
# now, following should work  ---> ssh username@localhost

Add macOS sudo Credentials into Ansible Inventory File

A number of tasks in the provision-osx Ansible role used in the installer require privilege escalation.

Add the name of the macOS user created in previous steps as a variable ansible_ssh_user into the Ansible inventory file.

This allows Ansible to run commands as sudo user.

Set ansible_sudo_pass variable or --ask-sudo-pass flag with the user password to enable the installer to work with root permissions.

Provide macOS with Internet Access to List of Hosts

Other external hosts may be required depending on what other packages you specify to install.
Table 1. Hosts and resources they provide:
Hostname Provides

https://github.com

Homebrew packages and Cocoapods

https://raw.githubusercontent.com

NVM - Node Version Manager

https://rvm.io

RVM - Ruby Version Manager

http://developer.apple.com

Apple Certificates and Xcode

https://npmjs.org

NPM packages

Using HTTP/HTTPS Proxy with Aerogear Digger (optional)

HTTP Proxies that require authentication are not supported. Please read the Known Issues for more details.

You can install AeroGear Digger behind a proxy by modifying variables in Ansible playbook.

The installer will automatically configure the following components to use proxy (if the component requires an outbound Internet access):

  • The Jenkins server

  • The Android SDK pod used to download Android SDKs

  • Container/node that will run the build jobs, by adding the environment variables such as HTTP_PROXY and HTTPS_PROXY in the inventory file.

  • macOS tools for iOS builds. See macOS Prerequisites (optional).

Ansible Variables for HTTP/HTTPS Proxy

Set these variables in an Inventory file, or with CLI.

Variable name

Description

proxy_url

This URL is pasted into http_proxy and https_proxy environment variables. Syntax: http://<proxy-host>:<proxy-port>; or http://<proxy_user>:<proxy_pass>@<proxy-host>:<proxy-port>;

proxy_host

The host address of the proxy server. e.g. 127.0.0.1

proxy_port

The port number of the proxy e.g. 8080

proxy_user

Required if proxy authentication is enabled

proxy_pass

Required if proxy authentication is enabled

proxy_protocol

Optional. The protocol to use with the proxy. Default value is http.

Using External Tools with HTTP/HTTPS Proxy

If you want to use the external tools with HTTP/HTTPS proxy, you will have to manually update the configuration for those tools in the Jenkinsfile, using the values from the environment variables such as HTTP_PROXY and HTTPS_PROXY.

Setup macOS Servers (optional)

Set the required variables to make installer provision a macOS server.

Steps done by installer to provision a macOS server
  1. Install Homebrew

  2. Install RVM and Ruby

  3. Install NVM and Node

  4. Install Xcode

  5. Download Apple certificates

  6. Update Cocoapods

  7. Register macOS Server as a node in Jenkins

Required Ansible Variables for macOS server provisioning

Variable name Description

xcode_install_user

Apple Developer Account username. If not set, Xcode installation will be skipped.

xcode_install_password

Apple Developer Account password. If not set, Xcode installation will be skipped.

credential_private_key_path

Path to the private key that Jenkins should use to SSH into the macOS node. If not set, the Jenkins node configuration will be skipped.

credential_passphrase

Passphrase for the private key. If not set, the Jenkins node configuration will be skipped.

credential_public_key_path

Path to the public key. The macOS node will add this to it’s authorized_keys file. If not set, the Jenkins node configuration will be skipped.

Example: Command setting required variables to start the Digger Ansible job to provision macOS server:
ansible-playbook -i sample-inventory-file sample-playbook.yml
-e "ansible_sudo_pass=exampleSudoPassword"
-e "xcode_install_user=exampleAppleDeveloperUsername"
-e "xcode_install_password=exampleAppleDeveloperPassword"
-e "credential_private_key_path=/path/to/sshKey"
-e "credential_passphrase=exampleSshKeyPassphrase"
-e "credential_public_key_path=/path/to/sshKey.pub"
--tags="provision-osx"

Further macOS Configuration options

Further configuration of the macOS node is possible through optional macOS variables.

Run Digger Installer

  1. Clone Digger Installer GitHub repo.

  2. Make a copy of the Ansible inventory-sample, and update it with information about your infrastructure.

    For a full list of variables that can be configured via the inventory file, refer to Installer Variables.
  3. Use one of these commands to run the playbook and follow the instructions printed in the terminal:

    • Command to install Digger with macOS server

      Make sure your macOS Server is prepared for installation. See macOS Prerequisities.
      ansible-playbook -i <your-inventory-sample> sample-build-playbook.yml
    • Command to install Digger without a macOS server

      ansible-playbook -i <your-inventory-sample> sample-build-playbook.yml --skip-tags=provision-osx
      As of Jan 4th 2018, only provision-osx tag is working with with --skip-tags.
  4. Perform nonautomated tasks manually:

    1. Accept Android SDK licence

      • During initial Android SDK installation

      • During sync of Android SDK versions

    2. If you are provisioning a macOS Server:

      • Copy server’s public SSH key(server that is running Ansible) into Jenkins Slave running on macOS server

      • Accept the Oracle License when installing Java on macOS server

Ansible playbook will perform the following tasks:
  • Check if the required Java version is installed, install/upgrade if not,

  • Create an OpenShift project,

  • Install Jenkins (Master) on OpenShift,

  • Install Android SDK to a Persistent Volume,

  • Configure Jenkins Master,

  • Setup macOS Server(s) (optional). Manual pre-provisioning is required.

  • Install Nagios on OpenShift,

  • Print URL and credentials for Jenkins and Nagios.

Nagios Installation Health checks

To monitor the status of Digger components, the Digger installer will also install Nagios and several Nagios checks. At the end of the installation, Ansible will trigger the checks and output the results.

To navigate to Nagios checks:
  1. Log in to Nagios using the URL and credentials printed in the terminal at the end of the installation.

  2. Navigate to the Services Link.

  3. Verify that all Nagios checks are passing.

The environment specific checks carried out by Nagios are:
  • Container CPU Usage

  • Container Memory Usage

  • Container Resource Limits

  • Pod Disk Storage

The Digger specific checks carried out by Nagios are:
  • Availability of the Jenkins container (pod)

  • Status of the network link between Jenkins and the macOS servers

  • Status of the Android SDK PersistentVolumeClaim

Installer Variables

This section describes all installer variables organized by tags.

For more information about these variables, see the Digger Installer repo

You must provide a value for all required variables or accept the default value.

You can specify a value using one of the following methods:

  • enter a value into the inventory file

  • specify a value on the command line

  • using an encrypted Ansible Vault file.

android-sdk

Variable name Description Default value Required

android_sdk_home

Location of Android SDK that is installed in the Android SDK container.

/opt/android-sdk-linux

No

configure-buildfarm

Variable name Description Default value Required

project_name

Name of the OpenShift project.

digger

No

add_public_key_automatically

Determines whether to add SSH public key to Jenkins configuration automatically.

true

No

jenkins_oauth_token

OAuth token

<oauth_token>

Yes, if add_public_key_automatically is set to true and enable_oauth is set to true.

concurrent_android_builds

Max. number of concurrent Android builds.

5

No

jenkins_private_key_password

Jenkins SSH private key password

None

Yes, if password protected

jenkins_private_key_path

Jenkins SSH private key location

~/.ssh/id_rsa

No

jenkins_public_key_path

Jenkins SSH public key location

~/.ssh/id_rsa.pub

No

jenkins_route_protocol

Route protocol used to connect to Jenkins

https

No

deploy-jenkins

Variable name Description Default value Required

project_name

Name of the OpenShift project.

digger

No

enable_oauth

Determines whether to enable OAuth OpenShift integration. If false, a static account will be created.

false

No

master_memory_limit

Maximum amount of memory the Jenkins master container can use.

3Gi

No

master_volume_capacity

Volume space available for data.

40Gi

No

deploy-nagios

Variables used to configure Nagios for sending alert emails.

Variable name Description Default value Required

smtp_server

SMTP server to send alert emails.

localhost

No

smtp_username

SMTP username.

username

No

smtp_password

Password of the SMTP user.

password

No

smtp_from_address

SMTP sender address.

admin@example.com

No

rhmap_admin_email

Destination address of alert emails.

root@localhost

No

jenkins_user

User who queries Jenkins during Nagios checks.

admin

No

jenkins_pass

User password for <jenkins_user>.

password

No

java

Variables used to configure JDK on the remote host that runs Jenkins CLI commands.

Variable name Description Default value Required

repo

The repository used to install JDK.

rhel-7-server-optional-rpms

No

java_version

JDK version to install.

1.8.0

No

login

Variables used to login to the OpenShift Cluster.

Variable name Description Default value Required

oc_user

OpenShift user who log into OpenShift.

Yes

oc_password

Password for <oc_user>.

Yes

login_url

URL used to log in to OpenShift.

https://localhost:8443

Yes

provision-osx

Variables used while provisioning a macOS node.

Variable name

Description

Default value

Required

ansible_become_pass

Sudo password required to perform root privileged actions on a macOS server. Typically, this is specified using the command line.

Yes

remote_tmp_dir

Location for temporary files.

/tmp

No

node_versions

A comma separated list of Node versions to install.

6

No

xcode_install_version

The version of the xcode-install tool to install.

2.2.1

No

gem_packages

A list of gem packages to install.

gem_packages:
- name: public_suffix
  version: 2.0.5
- name: xcode-install
  version: "{{xcode_install_version}}"

No

cocoapods_version

The version of the Cocoapods gem to install.

1.1.1

No

npm_packages

A list of global NPM packages to install.

npm_packages:
- name: cordova
  version: 7.0.1

No

homebrew_packages

The packages to install using Homebrew.

homebrew_packages:
- name: gpg
- name: grep
- name: jq

No

homebrew_version

The version of Homebrew to install (git tag).

1.3.1

No

homebrew_repo

The git repo for the version of Homebrew to install.

https://github.com/Homebrew/brew

No

homebrew_prefix

The parent directory for the Homebrew location.

/usr/local

No

homebrew_install_path

The location where Homebrew is installed.

<homebrew_prefix>/Homebrew

No

homebrew_brew_bin_path

The location where brew is installed.

/usr/local/bin

No

homebrew_paths

<homebrew_install_path>, <homebrew_brew_bin_path>, <homebrew_var_path>, /usr/local/Cellar, /usr/local/opt, /usr/local/share, /usr/local/etc, /usr/local/include

No

homebrew_taps

A list of Homebrew taps to add.

homebrew/core, caskroom/cask

No

xcode_install_user

Apple Developer Account username. If this is not set then Xcode is not installed.

Yes

xcode_install_password

Apple Developer Account password. If this is not set then Xcode is not installed.

Yes

xcode_install_session_token

Apple Developer Account auth cookie from fastlane spaceauth command (For accounts with 2FA enabled).

Yes

xcode_versions

A list of Xcode versions to install, can take over 30 minutes each to install.

'8.3.3'

No

xcode_default_version

The default version of Xcode to use

<xcode_version>[0]

No

apple_wwdr_cert_url

Apple WWDR certificate URL. Defaults to Apple’s official URL.

http://developer.apple.com/certificationauthority/AppleWWDRCA.cer

No

apple_wwdr_cert_file_name

Output file name of the downloaded WWDR certificate file.

AppleWWDRCA.cer

No

buildfarm_node_port

The port used to connect to the macOS node.

22

No

buildfarm_node_root_dir

Path to Jenkins root folder.

/Users/jenkins

No

buildfarm_credential_id

Identifier for the Jenkins credential object.

macOS_buildfarm_cred

No

buildfarm_credential_description

Description of the Jenkins credential object.

Shared credential for the macOS nodes in the buildfarm.

No

buildfarm_node_name

Name of the slave/node in Jenkins.

macOS (<node_host_address>)

No

buildfarm_node_labels

List of labels assigned to the macOS node.

ios

No

buildfarm_user_id

Jenkins user ID.

admin

No

buildfarm_node_executors

Number of executors (Jenkins configuration) on the macOS node. There is currently no build isolation for the macOS node. This means there is no guaranteed support for concurrent builds. This value should not be changed unless you are certain all apps will be built with the same signature credentials.

1

No

buildfarm_node_mode

How the macOS node should be utilised. The following options are available:

* NORMAL * EXCLUSIVE

Use EXCLUSIVE if you want build jobs with labels matching this node to only use this node.

NORMAL

No

buildfarm_node_description

Description of the macOS node in Jenkins.

macOS node for the buildfarm

No

project_name

The name of the digger Project in OpenShift

digger

No

proxy_host

Proxy url/base hostname to be used.

Yes if the macOS server only has outbound internet access via proxy

proxy_port

Proxy port to be used.

Yes if the macOS server only has outbound internet access via proxy

proxy_device

The proxy network device to use for proxy configuration.

Ethernet

No

proxy_ctx

A list of proxies to use.

webproxy, securewebproxy

No

buildfarm_lang_env_var

Value of LANG environment variable to set on the macOS node. CocoaPods requires a value of en_US.UTF-8.

en_US.UTF-8

No

buildfarm_path_env_var

$PATH environment variable to use in the macOS node.

$PATH:/usr/local/bin:/usr/bin:/bin:/usr/sbin:/sbin

No

credential_private_key

Private key stored in Jenkins and used to SSH into the macOS node. If this is not set, a key pair is generated.

No

credential_public_key

Public key of the pair. If this is not set, a key pair is generated.

No

credential_passphrase

Passphrase of the private key. This is stored in Jenkins and used to SSH into the macOS node. If this is not set, the private key is not password protected.

No

macOS Digger Variables

This is a list of variables divided into sections, each for an individual macOS server provisioning step.

Install Homebrew

This installation step will, along with Homebrew, also add taps and packages specified in the variables.

Table 2. osx_install_homebrew variables
Variable name Description

homebrew_version

The version of Homebrew to install (git tag).

homebrew_packages

The packages to install using Homebrew.

homebrew_packages:
- name: <PACKAGE_NAME>
- name: <PACKAGE_NAME>

homebrew_repo

The git repo where Homebrew resides (defaults to GitHub repo).

homebrew_prefix -homebrew_install_path

Where Homebrew will be installed, used as homebrew_prefix/homebrew_install_path.

homebrew_brew_bin_path

Where brew will be installed.

homebrew_taps

A list of taps to add.

Install Ruby

This step installs:

  • RVM

  • Ruby (single version)

  • cocoapods gem

  • Gems specified in gem_packages

Table 3. osx_install_ruby variables
Variable name Description

rvm_install_url

The URL of RVM installation script (defaults to GitHub release).

rvm_install_file_name

Defines the installation filename on the node.

rvm_gpg_url

The URL of the RVM-required gpg key.

rvm_gpg_file_name

File name given to the GPG public key required to verify RVM.

ruby_version

The version of Ruby to install.

cocoapods_version

Cocoapods gem version to install.

gem_packages

A list of gems to install.

gem_packages:
- name: <PACKAGE_NAME>
  version: <PACKAGE_VERSION>

Install Node.js

Installs: - NVM, - Nodejs, (versions defined in variable) - Optional packages from NPM, these will be installed globally.

Table 4. osx_install_nodejs variables
Variable name Description

nvm_install_url

URL of NVM installation script (defaults to GitHub release).

nvm_install_file_name

Define the nvm Install filename on the node

node_versions

A list of Node versions to install.

npm_packages

A list of global NPM packages to install.

npm_packages:
- name: <PACKAGE_NAME>
  version: <PACKAGE_VERSION>

Install Xcode

Installs:

  • XCode CLI tools

  • XCode - specified version

Installing a single version of XCode can take over 30 minutes, please be patient.

Xcode Two Factor Authentication (2FA) Support

You can disable 2FA in the Apple Developer Account for the duration of the Ansible job.

If you have 2FA enabled for the specified Apple Developer Account then you will need to set the xcode_install_session_token to a cookie provided by authenticating with Apple. This can be done using Fastlane Spaceship.

Fastlane 2.42.0 or higher is required
Obtaining Apple Developer cookie for 2FA Xcode installation
gem install fastlane -v '~> 2.42.0'
fastlane spaceauth -u <APPLE_DEVELOPER_USERNAME>

Follow the steps printed in the terminal. A cookie will be printed on the screen after successful authentication. Copy the cookie from ---\n to the last \n and provide this as the value for xcode_install_session_token.

Table 5. osx_install_xcode variables
Variable name Description

xcode_install_user

Apple Developer Account username. If this is not set then Xcode will not be installed.

xcode_install_password

Apple Developer Account password. If this is not set then Xcode will not be installed.

xcode_install_session_token

Apple Developer Account auth cookie from fastlane spaceauth command (For accounts with enabled 2FA).

xcode_versions

A list of Xcode versions to install. Installation of each version may take over 30 minutes.

Download Apple certificates

Downloads required certificates into the node. Currently, only Apple’s WWDR certificate is required. This certificate will be downloaded into the user’s home directory.

Table 6. osx_download_certs variables
Variable name Description

apple_wwdr_cert_url

Apple WWDR certificate URL. Defaults to Apple’s official URL

apple_wwdr_cert_file_name

Filename of the downloaded certificate. Default is AppleWWDRCA.cer.

Update Cocoapods

Executes pod repo update.

Configure Build Farm node

This step creates a credential set in the Build Farm for the macOS nodes using the provided keys. Add each machine as a node in the Build Farm, connecting through SSH.

You need to create a key pair using ssh-keygen(or similar tool) to allow the Jenkins instance to connect with the macOS nodes.

Generating A Key Pair With ssh-keygen

  1. Run ssh-keygen. -b is number of bits (2048 by default), -C an optional comment.

    ssh-keygen -t rsa -b 4096 -C "Digger-Jenkins-MacOS-Credentials"
  2. Select a location for the key pair along with a name.

    > Enter file in which to save the key:
    > ~/.ssh/digger_macos_rsa
  3. Enter a secure passphrase:

    > Enter passphrase (empty for no passphrase):
    > mySecurePassword
  4. Your key pair is available under the specified directory with the specified name:

    > ls ~/.ssh/
    digger_macos_rsa
    digger_macos_rsa.pub
Table 7. osx_configure_buildfarm variables
Variable name Description

credential_private_key

Private key stored in Jenkins and used to SSH into the macOS node. If not set, a key pair will be generated.

credential_public_key

Public key of the pair. If not set, a key pair will be generated.

credential_passphrase

Passphrase protecting the private key. This is stored in Jenkins and used to SSH into the macOS node. If not set, the private key will not be password protected.

buildfarm_node_port

The port used to connect to the macOS node. Default is 22.

buildfarm_node_root_dir

Path to Jenkins root folder. Default is /Users/jenkins.

buildfarm_credential_id

Identifier for the Jenkins credential object. Default is macOS_buildfarm_cred.

buildfarm_credential_description

Description of the Jenkins credential object.

buildfarm_node_name

Name of the slave/node in Jenkins. Default is macOS (<node_host_address>).

buildfarm_node_labels

List of labels assigned to the macOS node. Default is ios.

buildfarm_user_id

Jenkins user ID. Default is admin.

buildfarm_node_executors

Number of executors (Jenkins configuration) on the macOS node. Default is 1. Currently, there is no build isolation with the macOS node, that means there is no guaranteed support for concurrent iOS builds. Run concurrent builds only if ALL apps are to be built with the same signature credentials.

buildfarm_node_description

Description of the macOS node in Jenkins.

buildfarm_node_mode <MODE>

How the macOS node should be utilised. The following options are available:

<MODE> = NORMAL

Use this node as much as possible

<MODE> = EXCLUSIVE

Only build jobs with labels matching this node will use this node.

Table 8. Other variables
Variable name Description

remote_tmp_dir

A directory where downloaded scripts and other miscellaneous files can be stored for the duration of the job.

project_name

Name of the Jenkins project in OpenShift. Defaults to jenkins.

Known Issues

Issues with using HTTP Proxy

HTTP proxy with macOS Jenkins node

When configuring Jenkins to run behind a HTTP proxy, there is a limitation/bug in the way slave nodes use the Git plugins. This is because the slaves inherit proxy information from the master.

The result is that a macOS node (the Jenkins slave responsible for iOS builds), will attempt to checkout application source code through a HTTP proxy address and port if one has been specified during the provisioning of Digger.

This may not be an issue if the slave exists on the same network, but can be an issue if it exists on network outside the OpenShift cluster. Two potential workarounds exist:

  1. Add networking rules to allow the macOS server to route requests through the proxy. This is the recommended approach as it allows you to keep your Jenkins configuration intact.

  2. Remove the proxy configuration in Jenkins > Manage Jenkins > Manage Plugins > Advanced. If you then need to checkout source code behind a proxy for specific builds, the required configuration steps can be added to the Jenkinsfile when necessary.

HTTP proxy authentication in Android builds

When building Android apps, the pod in which the apps are built cannot use a proxy that requires authentication. This is due to an issue within Gradle.

Android SDK Manager tools don’t support HTTP proxy with authentication

(Regarding installation of Android SDK into the Android SDK OpenShift pod during provisioning).

Issues with Ansible provisioning

Encrypted private key cannot be provided in Ansible provisioning

The user’s private key cannot be encrypted when running the Ansible playbook.

Note that this does not include the key pair that should be provided when provisioning the macOS node, the private key of the macOS key pair should be encrypted with a passphrase.

The workaround is to use openssl to remove the passphrase from your key using the following command.

openssl rsa -in ~/.ssh/id_rsa -out ~/.ssh/id_rsa_new

iOS Build Limitations

No Build Isolation Support

At the moment(November 2017), the iOS builds do not support build isolation. This means if one iOS build process changes the settings/environment, it will impact all iOS build processes.

No Parallel Build Support On A Single macOS Server

Each iOS build needs to update parts of the global configuration (certifications, keys etc). If you need to support parallel iOS builds, you will need to configure multiple macOSservers.

redhatlogo-wite