Update documentation for TURN usage.

This updates the documentation and adds more details on how to configure
your own TURN server if needed. A TURN server is needed if the emulator
is hidden behind a VPN that does not permit UDP packets to go through.

We modify the launcher to make it easier to pass in the turn
configuration at container launch time.

Author: Erwin Jansen

README.md

@@ -4,7 +4,7 @@ This is a set of minimal scripts to run the emulator in a container for various
 systems such as Docker, for external consumption. The scripts are compatible
 with both Python version 2 and 3.
 
-*Note that this is still an experimental feature and we recommend installing
+\*Note that this is still an experimental feature and we recommend installing
 this tool in a [python virtual environment](https://docs.python.org/3/tutorial/venv.html).
 Please file issues if you notice that anything is not working as expected.
 
@@ -19,28 +19,28 @@ following requirements:
   installing the command line tools is sufficient.
 - [Docker](https://docs.docker.com/v17.12/install/) must be installed. Make
   sure you can run it as [non-root
-  user]((https://docs.docker.com/install/linux/linux-postinstall/))
+  user](https://docs.docker.com/install/linux/linux-postinstall/)
 - [Docker-compose](https://docs.docker.com/compose/install/) must be installed.
 - KVM must be available. You can get access to KVM by running on "bare metal",
   or on a (virtual) machine that provides nested virtualization. If you are planning to run
   this in the cloud (gce/azure/aws/etc..) you first must make sure you have
   access to KVM. Details on how to get access to KVM on the various cloud
   providers can be found here:
 
-    - AWS provides [bare
-      metal](https://aws.amazon.com/about-aws/whats-new/2019/02/introducing-five-new-amazon-ec2-bare-metal-instances/)
-      instances that provide access to KVM.
-    - Azure: Follow these
-      [instructions](https://docs.microsoft.com/en-us/azure/virtual-machines/windows/nested-virtualization)
-      to enable nested virtualization.
-    - GCE: Follow these
-      [instructions](https://cloud.google.com/compute/docs/instances/enable-nested-virtualization-vm-instances)
-      to enable nested virtualization.
+  - AWS provides [bare
+    metal](https://aws.amazon.com/about-aws/whats-new/2019/02/introducing-five-new-amazon-ec2-bare-metal-instances/)
+    instances that provide access to KVM.
+  - Azure: Follow these
+    [instructions](https://docs.microsoft.com/en-us/azure/virtual-machines/windows/nested-virtualization)
+    to enable nested virtualization.
+  - GCE: Follow these
+    [instructions](https://cloud.google.com/compute/docs/instances/enable-nested-virtualization-vm-instances)
+    to enable nested virtualization.
 
 Keep in mind that you will see reduced performance if you are making use of
 nested virtualization. The containers have been tested under Debian and Ubuntu running kernel 5.2.17.
 
-*NOTE: The images will not run in docker on mac or windows*
+_NOTE: The images will not run in docker on mac or windows_
 
 # Quick start with hosted containers.
 
@@ -49,8 +49,10 @@ We now host a set of containers in a public repository. You can find details abo
 
 ```sh
 docker run \
-  -e "ADBKEY=$(cat ~/.android/adbkey)" --device /dev/kvm --publish \
-  8554:8554/tcp --publish 15555:5555/tcp  \
+  -e ADBKEY="$(cat ~/.android/adbkey)" \
+  --device /dev/kvm \
+  --publish 8554:8554/tcp \
+  --publish 5555:5555/tcp  \
   us-docker.pkg.dev/android-emulator-268719/images/r-google-x64:30.0.23
 ```
 
@@ -60,7 +62,7 @@ starting:
 After this you can connect to the device by configuring adb:
 
 ```sh
-  adb connect localhost:15555
+  adb connect localhost:5555
 ```
 
 The device should now show up after a while as:
@@ -69,17 +71,19 @@ The device should now show up after a while as:
 $ adb devices
 
 List of devices attached
-localhost:15555 device
+localhost:5555 device
 ```
 
 If you wish to use this in a script you could do the following:
 
 ```sh
 docker run -d \
-  -e "ADBKEY=$(cat ~/.android/adbkey)" --device /dev/kvm --publish \
-  8554:8554/tcp --publish 15555:5555/tcp  \
+  -e ADBKEY="$(cat ~/.android/adbkey)" \
+  --device /dev/kvm \
+  --publish 8554:8554/tcp \
+  --publish 5555:5555/tcp  \
   us-docker.pkg.dev/android-emulator-268719/images/r-google-x64:30.0.23
-  adb connect localhost:15555
+  adb connect localhost:5555
   adb wait-for-device
 
   # The device is now booting, or close to be booted
@@ -88,7 +92,6 @@ docker run -d \
 
 A more detailed script can be found in [run-in-script-example.sh](./run-in-script-example.sh).
 
-
 # Install in a virtual environment
 
 You can install the python package as follows:
@@ -101,8 +104,7 @@ follows:
 
     emu-docker -h
 
-You will need to accept the android licenses when you are creating images. You will have
-to accept the license agreements before you can create docker containers.
+You will have to accept the license agreements before you can create docker containers.
 
 ## Quick start, interactively creating and running a docker image
 
@@ -130,8 +132,8 @@ command and check if a device is detected.
 
 Do not forget to stop the docker container once you are done!
 
-Read the [section](#Make-the-emulator-accessible-on-the-web) on making the emulator available on the web to run the emulator
-using webrtc
+Read the [section](#Make-the-emulator-accessible-on-the-web) on making the
+emulator available on the web to run the emulator using webrtc
 
 ## Obtaining URLs for emulator/system image zip files
 
@@ -145,7 +147,7 @@ of:
 - Available and currently Docker-compatible system images
 - Currently published and advertised emulator binaries
 
-For each system image, the API level, variant, ABI, and URL are displayed.  For
+For each system image, the API level, variant, ABI, and URL are displayed. For
 each emulator, the update channel (stable vs canary), version, host os, and URL
 are displayed.
 
@@ -179,7 +181,7 @@ Example output:
     EMU canary 29.0.12 linux https://dl.google.com/android/repository/emulator-linux-5613046.zip
 
 One can then use tools like `wget` or a browser to download a desired emulator
-and system image.  After the two are obtained, we can build a Docker image.
+and system image. After the two are obtained, we can build a Docker image.
 
 Given an emulator zip file and a system image zip file, we can build a directory
 that can be sent to `docker build` via the following invocation of `emu-docker`:
@@ -210,13 +212,15 @@ We provide the following run script:
 
 It does the following:
 
-    docker run -e "TOKEN=$(cat ~/.emulator_console_auth_token)" -e "ADBKEY=$(cat ~/.android/adbkey)" -e "EMULATOR_PARAMS=${PARAMS}" --device /dev/kvm --publish 8554:8554/tcp --publish 5554:5554/tcp --publish 5555:5555/tcp ${CONTAINER_ID}
-
+    docker run -e ADBKEY="$(cat ~/.android/adbkey)" \
+    --device /dev/kvm \
+    --publish 8554:8554/tcp \
+    --publish 5555:5555/tcp <docker-image-id>
 
 - Sets up the ADB key, assuming one exists at ~/.android/adbkey
 - Uses `--device /dev/kvm` to have CPU acceleration
 - Starts the emulator in the docker image with its gRPC service, forwarding the
-  host ports 8554/6664/5555 to container ports 8554/5554/5555 respectively.
+  host ports 8554/5555 to container ports 8554/5555 respectively.
 - The gRPC service is used to communicate with the running emulator inside the
   container.
 
@@ -238,9 +242,9 @@ You can now launch the emulator with the `run-with-gpu.sh` script:
 
 The script is similar as to the one described above with the addition that it will:
 
-  - Make all the available gpu's available (`--gpu all`)
-  - Opens up xhost access for the container
-  - Enable the domain socket under /tmp/.X11-unix to communicate with hosts X server
+- Make all the available gpu's available (`--gpu all`)
+- Opens up xhost access for the container
+- Enable the domain socket under /tmp/.X11-unix to communicate with hosts X server
 
 Hardware acceleration will significantly improve performance of applications that heavily
 rely on graphics. Note that even though we need a X11 server for gpu acceleration there
@@ -260,19 +264,19 @@ We adopted the following naming scheme for images:
 Where:
 
 - desert is the desert letter
-- sort is one of: *aosp*, *google*, *playstore*
-    - *aosp*: A basic android open source image
-    - *google*: A system image that includes access to Google Play services.
-    - *playstore*: A system image that includes the Google Play Store app and access to Google Play services,
-                   including a Google Play tab in the Extended controls dialog that provides a
-                   convenient button for updating Google Play services on the device.
-- abi indicates the underlying CPU architecture, which is one of: *x86*, *x64*, *a32*, *a64*.
+- sort is one of: _aosp_, _google_, _playstore_
+  - _aosp_: A basic android open source image
+  - _google_: A system image that includes access to Google Play services.
+  - _playstore_: A system image that includes the Google Play Store app and access to Google Play services,
+    including a Google Play tab in the Extended controls dialog that provides a
+    convenient button for updating Google Play services on the device.
+- abi indicates the underlying CPU architecture, which is one of: _x86_, _x64_, _a32_, _a64_.
   Note that arm images are not hardware accelerated and might not be fast enough.
 
-For example: *q-playstore-x86:29.3.2* indicates a playstore enabled system image with Q running on 32-bit x86.
+For example: _q-playstore-x86:29.3.2_ indicates a playstore enabled system image with Q running on 32-bit x86.
 
-*Note: We are in the process of migrating from version number to emulator build numbers,
- which are more accurate*
+_Note: We are in the process of migrating from version number to emulator build numbers,
+which are more accurate_
 
 An example invocation for publishing all Q images to google cloud repo could be:
 
@@ -283,7 +287,6 @@ An example invocation for publishing all Q images to google cloud repo could be:
 Images that have been pushed to a repository can be launched directly from the repository.
 For example:
 
-
 ```sh
     docker run --device /dev/kvm --publish 8554:8554/tcp --publish 5555:5555/tcp \
     us.gcr.io/emulator-project/q-playstore-x86:29.3.2
@@ -315,13 +318,13 @@ composing the following set of docker containers:
 
 - [Envoy](https://www.envoyproxy.io/), an edge and service proxy: The proxy is
   responsible for the following:
-    - Offer TLS (https) using a self signed certificate
-    - Redirect traffic on port 80 (http) to port 443 (https)
-    - Act as a [gRPC proxy](https://grpc.io/blog/state-of-grpc-web/) for the
-      emulator.
-    - Verifying tokens to permit access to the emulator gRPC endpoint.
-    - Redirect other requests to the Nginx component which hosts
-      a [React](https://reactjs.org/) application.
+  - Offer TLS (https) using a self signed certificate
+  - Redirect traffic on port 80 (http) to port 443 (https)
+  - Act as a [gRPC proxy](https://grpc.io/blog/state-of-grpc-web/) for the
+    emulator.
+  - Verifying tokens to permit access to the emulator gRPC endpoint.
+  - Redirect other requests to the Nginx component which hosts
+    a [React](https://reactjs.org/) application.
 - [Nginx](https://www.nginx.com/), a webserver hosting a compiled React App
 - [Token Service](js/jwt-provider/README.md) a simple token service that hands out
   [JWT](https://en.wikipedia.org/wiki/JSON_Web_Token) tokens to grant access to the emulator.
@@ -333,13 +336,13 @@ In order to run this sample and be able to interact with the emulator you must
 keep the following in mind:
 
 - The demo has two methods to display the emulator.
-    1. Create an image every second, which is displayed in the browser. This
-    approach will always work, but gives poor performance.
-    2. Use [WebRTC](https://webrtc.org/) to display the state of the emulator in
-       real time. This will only work if you are able to create a peer to peer
-       connection to the server hosting the emulator. This is usually not
-       a problem when your server is publicly visible, or if you are running the
-       emulator on your own intranet.
+  1. Create an image every second, which is displayed in the browser. This
+     approach will always work, but gives poor performance.
+  2. Use [WebRTC](https://webrtc.org/) to display the state of the emulator in
+     real time. This will only work if you are able to create a peer to peer
+     connection to the server hosting the emulator. This is usually not
+     a problem when your server is publicly visible, or if you are running the
+     emulator on your own intranet.
 
 ## Requirements
 
@@ -348,23 +351,15 @@ keep the following in mind:
   internal network and expose the http and https ports.
 - You will need to create an emulator docker image, as described in the
   documentation above.
+- Depending on your network you might need [turn](js/turn/README.MD)
 
 ## Running the emulator on the web
 
-
 In order to create the web containers you must have the following tools available:
 
-- A protobuf compiler and headers
-- GNUmake
 - NodeJS
-- Package config
 - Npm
 
-On debian based systems you can install these as follows:
-
-    sudo apt-get install build-essential nodejs npm libprotoc-dev protobuf-compiler pkg-config
-
-
 Next you must create a container with the emulator & system image version you wish to
 use. For example:
 
@@ -392,6 +387,7 @@ For example:
 ```sh
 ./create_web_container.sh -p user1,passwd1,user2,passwd2,....
 ```
+
 This will do the following:
 
 - Create a virtual environment
@@ -413,7 +409,6 @@ js/docker/development.yaml as follows:
 docker-compose -f js/docker/docker-compose.yaml -f js/docker/development.yaml up
 ```
 
-
 Point your browser to [localhost](http://localhost). You will likely get
 a warning due to the usage of the self signed certificate. Once you accept the
 cert you should be able to login and start using the emulator.
@@ -422,9 +417,10 @@ Keep the following things in mind when you make the emulator accessible over adb
 
 - Port 5555 will be exposed in the container.
 - The container must have access to the file: `~/.android/adbkey`. This is
-  the *PRIVATE* key used by adb.
+  the _PRIVATE_ key used by adb. Without this you will not be able to access the device
+  over adb.
 - The adb client you use to connect to the container must have access to the
-  private key (~/.android/adbkey).  This is usually the case if you are on the same machine.
+  private key (~/.android/adbkey). This is usually the case if you are on the same machine.
 - You must run: `adb connect ip-address-of-container:5555` before you can
   interact with the device. For example: