Improve README build instructions & add troubleshooting (#97)

* Improve README build instructions & add troubleshooting

* Improve README build instructions & add troubleshooting

* remove trailing whitespace XCode did not trim

Author: mrutkows

.travis.yml

@@ -45,17 +45,17 @@ deploy:
     on:
       tags: true
       all_branches: true
-      repo: apache/incubator-openwhisk-runtime-java
+      repo: apache/openwhisk-runtime-java
   - provider: script
     script: "./tools/travis/publish.sh openwhisk 8 nightly"
     on:
       branch: master
-      repo: apache/incubator-openwhisk-runtime-java
+      repo: apache/openwhisk-runtime-java
   - provider: script
     script: "./tools/travis/publish.sh openwhisk 8a nightly"
     on:
       branch: master
-      repo: apache/incubator-openwhisk-runtime-java
+      repo: apache/openwhisk-runtime-java
 env:
   global:
   - secure: D4kU9O6bs63Myb4jaEgw1O2Kuy6aTAUKEX1qZ0eYMDouLnPOPnZaFWmpISKTrJyz7hJH7yY8Cj7xl5qwsLB6JZZMtqT6yj5J/jkUJjyLKdQH81PrYy22rH99xS2t5A1dsC0A/Bf39R/qNc5tx1wCMVDF4O2rFsUtn+8vE+rn0nXsiPeWhhZagk/Hrq8YbwzDJHOGHfWe1nZIcU8MORzTriX7J2VAF0AcirPandMxff4FgzNLk432DN2GvgZIlNtZGT1DWLtJV/Sp3unD9abXr5xqNDIW+fHrMq8j/JdHC6+PFtZRFrl0Vr6X8c61PkB/ELGF2MyzNgBTnEaJixl1pianr91WK4y0oLUwpSJCz4yoQGVimAAtqMgNXjEyFMcpLClzS5TjMXKaUfi9mBn9GMCwLi3VAuVtMtH2IRW03PxIPyxkbj1j8Nrd0jh408MuMpuzyECgb+E5ffbd+0YD5XUNlTkYLFi4sEh2xpzvjGrNbrTe99zFrHt3e+dbmoahmaCyDRsxD2CDI8b++HyN78z/jO9A7kFc2TAZbWa6Xygkj1nEpnR1y4TB6eqdDo7Y6W20dLjeSSF8rACw3bM3lJh+K4/nv4Nlo6pfblhvs7T53ftst+tHpxJoQy/gDC0TcuyBThrHTeI1j7k4HkQyN+NqezBdFN2ElufjQ74ds2c=

README.md

@@ -19,7 +19,7 @@
 
 # Apache OpenWhisk runtimes for java
 
-[![Build Status](https://travis-ci.org/apache/incubator-openwhisk-runtime-java.svg?branch=master)](https://travis-ci.org/apache/incubator-openwhisk-runtime-java)
+[![Build Status](https://travis-ci.org/apache/openwhisk-runtime-java.svg?branch=master)](https://travis-ci.org/apache/openwhisk-runtime-java)
 
 ## Changelogs
 - [Java 8 CHANGELOG.md](core/java8/CHANGELOG.md)
@@ -94,19 +94,40 @@ wsk action invoke --result helloJava --param name World
 ```
 
 ## Local development
+
+### Pre-requisites
+- Gradle
+- Docker Desktop (local builds)
+
+### Build  and Push image to a local Docker registry
+
+1. Start Docker Desktop (i.e., Docker daemon)
+
+2. Build the Docker runtime image locally using Gradle:
 ```
 ./gradlew core:java8:distDocker
 ```
-This will produce the image `whisk/java8action`
+This will produce the image `whisk/java8action` and push it to the local Docker Desktop registry with the `latest` tag.
+
+3. Verify the image was registered:
+```
+$ docker images whisk/*
+REPOSITORY           TAG     IMAGE ID            CREATED             SIZE
+whisk/java8action    latest  35f90453905a        7 minutes ago       521MB
+```
+
+### Build and Push image to a remote Docker registry
 
-Build and Push image
+Build the Docker runtime image locally using Gradle supplying the image Prefix and Registry domain (default port):
 ```
 docker login
 ./gradlew core:java8:distDocker -PdockerImagePrefix=$prefix-user -PdockerRegistry=docker.io
 ```
 
+## Deploying the Java runtime image to OpenWhisk
+
 Deploy OpenWhisk using ansible environment that contains the kind `java:8`
-Assuming you have OpenWhisk already deploy locally and `OPENWHISK_HOME` pointing to root directory of OpenWhisk core repository.
+Assuming you have OpenWhisk already deployed locally and `OPENWHISK_HOME` pointing to root directory of OpenWhisk core repository.
 
 Set `ROOTDIR` to the root directory of this repository.
 
@@ -159,7 +180,35 @@ wsk action update helloJava hello.jar --main Hello --docker $user_prefix/java8ac
 ```
 The `$user_prefix` is usually your dockerhub user id.
 
+---
+
+# Troubleshooting
+
+### Gradle build fails with "Too many files open"
+
+This may occur on MacOS as the default maximum # of file handles per session is `256`.  The gradle build requires many more and is unable to open more files (e.g., `java.io.FileNotFoundException`).  For example, you may see something like:
+
+```
+> java.io.FileNotFoundException: /Users/XXX/.gradle/caches/4.6/scripts-remapped/build_4mpzm2wl8gipqoxzlms7n6ctq/7gdodk7z6t5iivcgfvflmhqsm/cp_projdf5583fde4f7f1f2f3f5ea117e2cdff1/cache.properties (Too many open files)
+
+```
+You can see this limit by issuing:
+```
+$ ulimit -a
+open files                      (-n) 256
+```
+
+In order to increase the limit, open a new terminal session and issue the command (and verify):
+```
+$ ulimit -n 10000
+
+$ ulimit -a
+open files                      (-n) 10000
+```
+
+### Gradle Task fails on  `:core:java8:tagImage`
 
+Docker daemon is not started and the Task is not able to push the image to your local registry.
 
 # License
 [Apache 2.0](LICENSE.txt)

core/java8actionloop/Dockerfile

@@ -15,7 +15,7 @@
 # limitations under the License.
 #
 FROM golang:1.12 as builder
-RUN env CGO_ENABLED=0 go get github.com/apache/incubator-openwhisk-runtime-go/main
+RUN env CGO_ENABLED=0 go get github.com/apache/openwhisk-runtime-go/main
 
 FROM adoptopenjdk/openjdk8:x86_64-ubuntu-jdk8u212-b03
 

tools/travis/build.sh

@@ -23,7 +23,7 @@ set -ex
 SCRIPTDIR=$(cd $(dirname "$0") && pwd)
 ROOTDIR="$SCRIPTDIR/../.."
 WHISKDIR="$ROOTDIR/../openwhisk"
-UTILDIR="$ROOTDIR/../incubator-openwhisk-utilities"
+UTILDIR="$ROOTDIR/../openwhisk-utilities"
 
 export OPENWHISK_HOME=$WHISKDIR
 

tools/travis/setup.sh

@@ -26,9 +26,9 @@ HOMEDIR="$SCRIPTDIR/../../../"
 
 # clone OpenWhisk utilities repo. in order to run scanCode
 cd $HOMEDIR
-git clone https://github.com/apache/incubator-openwhisk-utilities.git
+git clone https://github.com/apache/openwhisk-utilities.git
 
 # clone main openwhisk repo. for testing purposes
-git clone --depth=1 https://github.com/apache/incubator-openwhisk.git openwhisk
+git clone --depth=1 https://github.com/apache/openwhisk.git openwhisk
 cd openwhisk
 ./tools/travis/setup.sh