STF IOS Support

Actual instruction for deploy service on 2023/08/09

Prerequisites

1. A machine running MacOS ( to build and run the "provider" )
2. A machine running Linux with Docker container support ( to run the STF server )

Build machine setup

1. Clone this repo down to your build machine

2. Install XCode

3. Add your developer Apple ID to XCode

   1. XCode -> XCode menu -> Preferences -> Accounts Tab
   2. Click + under Apple IDs list
   3. Choose Apple ID
   4. Login to your account

4. Download a "Apple Development certificate" for your user

   1. Continue from previous step, right after logging into your Developer account in Xcode
   2. Select Manage Certificates
   3. Click + in the lower left corner
   4. Select Apple Development

5. Clone the various needed repos ( includes WebDriverAgent )

   1. Run make clone

6. Configure WebDriverAgent to use your identity for signing

   1. Open repos/WebDriverAgent/WebDriverAgent.xcodeproj in XCode
   2. Select the WebDriverAgentLib target
   3. Go to the Signing & Capabilities tab
   4. Select your team under Team
   5. Select the WebDriverAgentRunner target
   6. Go to the Signing & Capabilities tab
   7. Select your team under Team

7. Run ./init.sh

Deploy server side:

1. On your Linux machine

   1. Copy server folder to your Linux machine

   2. Run server/cert/gencert.sh to generate a self-signed cert ( or use your own )

   3. Note! Plain http STF server is not supported. It can be done, but it shouldn't and tickets to make it so will be closed.

   4. Update server/.env to reflect the IP and hostname for your server

   5. Start STF

      1. docker-compose up

Using a standard OpenSTF server:

1. Setup your server as normal following upstream instructions
2. Create an SSL certificate for your server using the method you desire.
3. Configure the OpenSTF server for SSL
4. Alter stf_ios_support/coordinator/proc_stf_provider --connect-sub and --connect-push lines to match your server config

Build provider files:

1. Copy the first {} block from config.json.example into config.json. Do not include any comment lines starting with //

2. Update config.json

   1. Update xcode_dev_team_id to be the OU of your developer account. If you add your account into Xcode first, you can then run make ou to display what the OU is. You can also find it by opening the keychain, selecting the Apple Development certificate for your account, and then looking at what the Organization Unit is.
   2. Update root_path to be where provider code should be installed, such as /Users/user/stf
   3. Update config_path to match that, such as /Users/user/stf/config.json

3. Run make then make dist

   1. dist.tgz will be created

Deploy provider setup:

1. Copy dist.tgz from build machine
2. Run tar -xf dist.tgz
3. Tweak config.json as desired

Starting provider

1. Register(provision) your IOS device to your developer account as a developer device.

   1. Use the API -or-

      1. Follow https://developer.apple.com/documentation/appstoreconnectapi/creating_api_keys_for_app_store_connect_api to create an app store connect API key. Give it Developer access.
      2. Gain a session using JSON Web Tokens
      3. Create a provisioning profile if none exist using profiles: https://developer.apple.com/documentation/appstoreconnectapi/profiles See also https://github.com/cidertool/asc-go/blob/f08b8151f7fd92ff54924480338dafbf8a383255/asc/provisioning_profiles.go
      4. Post to the devices endpoint to register a device: https://developer.apple.com/documentation/appstoreconnectapi/devices See also https://github.com/cidertool/asc-go/blob/f08b8151f7fd92ff54924480338dafbf8a383255/asc/provisioning_devices.go

   2. Follow these instructions: https://www.telerik.com/blogs/how-to-add-ios-devices-to-your-developer-profile I couldn't find updated instructions on Apple's website. If you find them please let me know so I can link to them.

2. Plug your IOS device in

3. Pair it with your system

   1. Run idevicepair pair
   2. Accept pairing on IOS device screen

4. Have Xcode setup the "developer image" on your IOS device:

   1. Open Xcode
   2. Go to Windows... Devices and Simulators
   3. Wait while Developer Image is installed to your phone

5. Run ./bin/ios_video_pull -devices -decimal to determine the PID ( product ID ) of your IOS device in decimal

6. Run ./bin/devreset [decimal product ID] 1452 to reset the video streaming status of your IOS device

7. Run ./run ( and leave it running )

8. Permissions dialog boxes appear for coordinator to listen on various ports; select accept for all of them

9. Device shows up in STF with video and can be controlled. Yay

Using runner

Runner is a command that runs coordinator in a loop and also enables installation/update of a distribution. Runner is not necessary to use stf_ios_support. It is provided to make it easier to remotely maintain a cluster of providers. To use it:

1. Run make to build all the things

2. Run runner/runner -pass [some password] to generate crypted password of your choice

3. Adjust runner/runner.json

   1. Update user password with the crypted output of previous step
   2. Update user to something else ( default user/pass are both replaceme )
   3. Update update_server to be host/IP address of the server you will use to run update_server
   4. Update updates path to be path on a provider machine where you want downloaded updates to be saved/cached
   5. Update install_dir path to be the path where you want coordinator to be installed
   6. Update config path to be a path where config.json for coordinator will be located on provider machine

4. Rerun make to rebuild runner.tgz

5. Run make updatedist to build update_server.tgz

6. Copy update_server.tgz to a server

7. Extract it

   1. tar -xf update_server

8. Run it and leave it running

   1. update_server/server

9. Copy runner.tgz to a provider machine

10. Extract it

    1. tar -xf runner.tgz

11. Stop any instance you may be running of coordinator already on the provider

12. Run it in a visual GUI MacOS session

13. Go to https://[provider ip/host]:8021 in your browser

14. Accept the self-signed cert ( or make your own non-self signed cert and adjust updaet_server config )

15. Click the update button to download/install/start coordinator on the provider

Known Issues

1. libimobiledevice won't install properly right now from brew

   1. ./init.sh
   2. make libimd ( init.sh actually already runs this )

2. Video streaming will sometimes be left in a "stuck" state

   1. ios_video_pull sub-process of coordinator depends on quicktime_video_hack upstream repo/library. That library does not properly "stop" itself if you start and then stop reading video from an IOS device. As a result, if you run coordinator, stop it, then start it again, it won't be able to start up again correctly.
   2. To fix this you can use devreset. This is why the devreset command is mentioned above currently to run before starting coordinator. devreset effectively stops the video streaming entirely, resetting it so that it can be started up again.

Setting up with VPN

1. Install openvpn-server on your STF server machine
2. Create client certificate(s) using your favorite process...
3. Create ovpn file(s) with those client certs
4. Deploy those cert(s) to your provider machines; setting them up in Tunnelblick
5. Alter config.json on each provider to have the name of the cert setup in Tunnelblick
6. Start openvpn server on STF server
7. Start coordinator/provider on each provider machine

Handling video not working

1. Run ./view_log proc ios_video_pull to check for errors fetching h264 data from the IOS device
2. Run ./view_log -proc ios_video_stream to check for errors streaming jpegs via websocket to browser
3. Reboot your IOS device and try again

Debugging

1. run ./view_log to see list of things that log
2. run ./view_log -proc [one from list]

FAQ

See https://github.com/devicefarmer/stf_ios_support/wiki/FAQ