Skip to content
mcilvena edited this page Sep 30, 2014 · 8 revisions

Server Setup

The following steps assume that you are installing Hockey on an Apache server.

  1. Have a server with PHP 5 support accessible to your potential testers

  2. Create a directory which will hold your applications, later referred as the public server directory.

  3. Copy the content of the public directory in the repository, including the .htaccess file (!), onto your server into the public server directory created in 2.

  4. Create another directory on your server, preferably outside the public accessible HTML path (for better security), later referred as the include server directory

  5. Copy the content of the includes directory into this include server directory created in step 4

  6. Open the public server directory created in 2. and open the config.php file in an editor. Adjust the path to relatively point to the include server directory created in 4.

  7. Open the stats directory inside the public server directory

  8. Grant the php process write access to the stats directory, usually be activating write access for the unix group. Some users report changing the owner to the web server user did the trick for them. This may vary depending on your hosting environment.

  9. To restrict access to the stats directory open the .htaccess file inside the stats directory in an editor

  10. Adjust the AuthUserFile parameter to point to a .htpasswd file containing the user and password to access the stats page via a browser

    Note: Refer to your server documentation on how to generate a .htpasswd file. For more information check out the Apache documentation

    Note: Make sure the server is set to override directory specific settings in the hockey folder, in Apache this is handled with the AllowOverride All setting. And also make sure it has rewrite rules enabled, in Apache this is usually done with the following line:

    LoadModule rewrite_module libexec/apache2/

Setup a new application

  1. Open the public server directory

  2. Create a new subdirectory with the name of the bundle identifier of your application, e.g. com.yourcompanyname.myapplicationbeta, later referred as the application directory

    It is highly recommended to use separate bundle identifiers for the release, beta and debug version of your application. This way you and the testers can use them side by side on the device which makes testing easier and always having a fallback possibility. For developers this eases bug reports reported for release versions.

Add a new app version

There are two options to add an actual application version. You can later migrate between these two pretty easily, but lets make the differences clear first. The first option is to have only one version of an app available. This means that every new version will have to overwrite the previous files on the server.

Please note that there may be only one file of each type present in a directory. If there are multiple files of a type, the server will randomly choose one.

By default only the extension name of a file is important and visible by showing a "." at the beginning of the file definition, the name of the file can be anything. There are exceptions, of course.

The second option having multiple versions per application stored, is required to use the feature Team Management and allowing the Hockey client to present all release notes for all available versions. It is highly recommended to use this option.

Distribute single version only

  1. Upload the app package into the application directory

    iOS: The app package is a .ipa file.

    Android: The app package is a .apk file.

  2. Upload the application manifest file into the application directory

    iOS: This is a .plist file, the format is defined in the appendix

    Android: This is a .json file, the format is defined in the appendix

Distribute and manage multiple versions

Ever single version of the application has to be stored into its own subdirectory under the application directory, referred to as version directory. For obscurity reasons, it is possible to add a prefix string to the name of each version directory. This prefix string has to be identical for each version inside a application directory. Hockey will reverse sort the subdirectories to identify the latest version.

Example version directory names:


In this example, the version directory aksufy5 will contain the latest version.

Once a new version directory has been added, simply upload the files mentioned above in Only have one version available into this version directory instead.


  1. Adding Release Notes

    Release notes are written in HTML and provided in a .html file in the same directory as the application package is located

  2. Adding Application Icon

    The application images can be provided as a .png file, copied into the application directory

  3. Hiding application from main web page

    Place a file named private into the application directory. This will hide the application from the main page and make it only accessible via the application specific web page. To get that specific page add /apps/bundleidentifier to your hockey installation path, where bundleidentifier is the bundle identifier of the requested application, e.g. Watch for case-sensitivity of the bundle identifier!

  4. Restricting access to specific teams (iOS only)

    Place a .team file inside the version directory. Add a comma separated list of team strings which will get access to this specific app version. If non of the team strings is actually associated to any device, this app version will not be available for anybody. Definition of the possible team strings, will be described below in TODO

    Please note that there has to be at least one version without team access available, otherwise you would have to distribute individual versions via email or something else. That is because app version restricted for a team will not be shown on the web page, so initial installation will not be possible!

Define devices and teams (iOS only)

Defining the devices is required to enable the Team Management, Device Authentication and Stats features. The definition of a team is optional, but required if the Team Management feature should be used. The file to edit is named userlist.txt and located inside the stats directory, which itself is inside the public server directory.


# UDID;the testers name;team1,team2
C8E3F82A-4E2B-5509-A1BE-52984C5CE592;Andreas Linde;hockeycore
C8E3F82A-4E2B-5509-A1BE-52984C5CE593;Stanley Rost;hockeycore
C8E3F82A-4E2B-5509-A1BE-52984C5CE594;Dummy User

The file defined one device per line, comments are allowed by starting a line with the # character. Each line defines its data semicolon separated and the optional team names are comma separated


  • The first element defined the device UDID
  • The second element defines the name to be shown for this device, usually the owners name
  • The third element is optional, and defines the associated team strings to this device. So team strings are defined implicitly by adding any string to a device.

Import devices

It is possible to import the UDID strings and names from the Apple developer portal. Follow these steps:

  1. Invoke the /stats/index.php page in the browser on your desktop computer
  2. Follow the instructions shown in the footer of the page.
You can’t perform that action at this time.