Apart from being able to continuously build new versions of mobile applications, Hydra offers another interesting benefit -- we can use a web browser on an Android device, such as a phone or tablet (or even an emulator instance) to open the Hydra web interface, and conveniently install any Android app by simply clicking on the resulting hyperlink to an APK bundle.
It is also possible to automatically deliver iOS apps in a similar way. However, accomplishing this with Hydra turns out to be quite tedious and complicated. In this blog post, I will explain what I did to make this possible.
Wireless adhoc distributions of iOS apps
According to the following webpage: http://gknops.github.io/adHocGenerate two requirements have to be met in order to provide wireless adhoc releases of iOS apps.
First, we must compose a plist file containing a collection of meta attributes of the app to be distributed. For example:
<plist version="1.0">
<dict>
<key>items</key>
<array>
<dict>
<key>assets</key>
<array>
<dict>
<key>kind</key>
<string>software-package</string>
<key>url</key>
<string>http://192.168.1.101/Renamed.ipa</string>
</dict>
</array>
<key>metadata</key>
<dict>
<key>bundle-identifier</key>
<string>com.myrenamedcompany.renamedapp</string>
<key>bundle-version</key>
<string>1.0</string>
<key>kind</key>
<string>software</string>
<key>title</key>
<string>Renamed</string>
</dict>
</dict>
</array>
</dict>
</plist>
The above plist file defines a software package with bundle id: com.myrenamedcompany.renamedapp, version: 1.0 and name: Renamed. The corresponding IPA bundle is retrieved from the following URL: http://192.168.1.101/Renamed.ipa.
The second thing that we have to do is opening a specialized URL in the browser of an iOS device that refers to the plist file that we have defined earlier:
itms-services://?action=download-manifest&url=http://192.168.1.101/distribution.plist
If the plist file properly reflects the app's properties and the signing of the IPA file is done right, e.g. the device is authorized to install the app, then it should be automatically installed on the device after the user has accepted the confirmation request.
Generating a plist file and link page in a Nix/Hydra build
At first sight, integrating wireless adhoc distribution support in Nix (and Hydra) builds seemed to look easy to me -- I just generate the required plist file and an HTML page containing the specialized link URL (that gets clicked automatically by some JavaScript code) and expose these files as Hydra build products so that they are accessible from Hydra's web interface.
Unfortunately, it turned out it is actually a bit more complicated than I thought -- the URLs to the plist and IPA files must be absolute. An absolute path to an IPA file served by Hydra may look as follows:
http://192.168.1.101/build/35256/download/1/Renamed.ipa
Two components of the URL are causing a bit of inconvenience. First, we must know the hostname of the Hydra server. If I would make this value a build property, then the build becomes dependent on Hydra's hostname, which forces us to rebuild the app if it changes for some reason.
Second, the URL contains a unique build id assigned by Hydra that we do not know while performing the build. We have to obtain this value by some other means.
Solution: using page indirection
To solve this problem, I used a very hacky solution introducing an extra layer of indirection -- I have adapted the Nix function that builds iOS applications to generate an HTML file as a Hydra build product from the following template:
<!DOCTYPE html>
<html>
<head>
<title>Install IPA</title>
</head>
<body>
<a id="forwardlink" href="@INSTALL_URL@">
Go to the install page or wait a second
</a>
<script type="text/javascript">
setTimeout(function() {
var link = document.getElementById('forwardlink');
if(document.createEvent) {
var eventObj = document.createEvent('MouseEvents');
eventObj.initEvent('click', true, false);
link.dispatchEvent(eventObj);
} else if(document.createEventObject) {
link.fireEvent('onclick');
}
}, 1000);
</script>
</body>
</html>
What the above page does is showing a hyperlink that redirects the user to another page. Some JavaScript code automatically clicks on the link after one second. After clicking on the link, the user gets forwarded to another web page that is responsible for providing the installation link. We use this obscure page indirection trick to allow the next page to extract some relevant Hydra properties from the referrer URL.
The build script substitutes the @INSTALL_URL@ template property by a relative (or absolute) path that may look as follows:
/installipa.php?bundle=com.myrenamedcompany.renamedapp&version=1.0&title=Renamed
Besides forwarding the user to another page, we also pass the relevant build properties that we need to generate a plist file as GET parameters. Furthermore, the generated HTML build product's URL has nearly the same structure as the URL of an IPA file:
http://192.168.1.101/build/35256/download/2/Renamed.html
The fact that the build product URL of the redirection page has nearly the same structure makes it quite easy for us to extract the remaining properties (the hostname and build id) we need to generate the plist file.
The PHP page that we link to (/installipa.php) is responsible for generating a web page with the specialized itms-services:// URL that triggers an installation. With the following PHP code we can extract the hostname, app name and build id from the referrer URL:
$url_components = parse_url($_SERVER["HTTP_REFERER"]); $hostname = $url_components["host"]; $app_path = dirname(dirname($url_components["path"])); $app_name = basename($url_components["path"], ".html");
We can determine the protocol that is being used as follows:
if($_SERVER["HTTPS"] == "")
$protocol = "http://";
else
$protocol = "https://";
And compose the absolute IPA URL out of the previous variables:
$ipa_url = $protocol.$hostname.$app_path."/1/".$app_name.".ipa";
Then we display a hyperlink with the specialized installation URL that is generated as follows:
<?php
$plistURL = $protocol.$hostname."/distribution.plist.php".$plistParams;
?>
<a href="itms-services://?action=download-manifest&url=<?php print($plistURL); ?>">
Click this link to install the IPA
</a>
The plist file that the itms-services:// URL refers to is another PHP script that generates the plist dynamically from a number of GET parameters. The GET parameters are composed as follows:
$plistParams = urlencode("?ipa_url=".$ipa_url.
"&bundleId=".$_REQUEST["bundleId"].
"&version=".$_REQUEST["version"].
"&title=".$_REQUEST["title"]);
By applying the same JavaScript trick shown earlier, we can also automatically click on the installation link to save the user some work.
Adapting Hydra's configuration to use the IPA installation script
To allow users to actually do wireless adhoc installations, the two PHP scripts described earlier must be deployed to the Hydra build coordinator machine. If NixOS is used to deploy the Hydra coordinator machine, then it is simply a matter of adding a few additional configuration properties to the HTTP reverse proxy service section of its NixOS configuration file:
services.httpd = {
enable = true;
adminAddr = "admin@example.com";
hostName = "hydra.example.com";
extraModules = [
{ name = "php5"; path = "${pkgs.php}/modules/libphp5.so"; }
];
documentRoot = pkgs.stdenv.mkDerivation {
name = "distribution-proxy";
src = pkgs.fetchgit {
url = https://github.com/svanderburg/nix-xcodeenvtests.git;
rev = "0ba187cc83941bf16c691094480f0632b8116e48";
sha256 = "4f440e4f3c7b58c40b86e2c8c18608606b64bf341aed233519e9023fff1ceb01";
};
buildCommand = ''
mkdir -p $out
cp $src/src/distribution-proxy/*.php $out
'';
};
extraConfig = ''
<proxy>
Order deny,allow
Allow from all
</proxy>
ProxyPass /installipa.php !
ProxyPass /distribution.plist.php !
ProxyRequests Off
ProxyPreserveHost On
ProxyPass / http://localhost:3000/ retry=5 disablereuse=on
ProxyPassReverse / http://localhost:3000/
'';
};
What I did in the above reverse proxy server configuration snippet, is configuring the documentRoot to refer to a folder containing the two PHP scripts we have shown earlier. The scripts are retrieved from a Git repository. Before I configure the reverse proxy, I declare that two request URLs, namely: the PHP scripts, should not be forwarded to Hydra's Catalyst server.
Usage
After setting up a Hydra instance that hosts these two PHP scripts, we can build an iOS app (such as our trivial example testcase) that includes an HTML forwarding page that allows us to automatically install the app on an iOS device. This can be done with the following expression:
{xcodeenv}:
xcodeenv.buildApp {
name = "Renamed";
src = ../../src/Renamed;
release = true;
certificateFile = /Users/sander/mycertificate.p12;
certificatePassword = "secret";
codeSignIdentity = "iPhone Distribution: My Cool Company";
provisioningProfile = /Users/sander/provisioningprofile.mobileprovision;
generateIPA = true;
enableWirelessDistribution = true;
installURL = "/installipa.php";
bundleId = "com.mycoolcompany.renamed";
version = "1.0";
title = "Renamed";
}
Setting the enableWirelessDistribution parameter to true makes the build function generating the HTML page as build product. The installURL, bundleId, version and title parameters are used for the page forwarding and the plist file generation.
Result
By setting up a Hydra jobset using the above function, we can open the Hydra web application in a web browser on an iOS device and navigate to an iOS build:
Clicking on the 'Documentation of type install' build product does our page forwarding trick. After 2 seconds a confirmation dialog should appear:
After clicking on the 'Install' button, the app gets installed and appears in the program menu:
And finally we can run it! Isn't it great?
Concluding remarks
In this blog post I have described a hacky method using page indirection making it possible to use Hydra to do wireless adhoc distributions of iOS apps.
Unfortunately, I also discovered that for devices running iOS 7.1 and onwards, an HTTPS connection to the plist and IPA files is required, with a valid, trustable cross-signed certificate, making things even more tedious and complicated.
The hacky PHP scripts described in this blog post are part of the Nix xcode test package that can be obtained from my GitHub page.
It is also quite funny to realise that all these steps are not required at all for Android apps. Simply making APK files available for download is enough.