Docs update for local dev (#5134)
diff --git a/ansible/README.md b/ansible/README.md
index 7cc05f8..692b01d 100644
--- a/ansible/README.md
+++ b/ansible/README.md
@@ -27,15 +27,15 @@
#### Ubuntu users
```shell script
sudo apt-get install python-pip
-sudo pip install ansible==2.5.2
-sudo pip install jinja2==2.9.6
+sudo pip install ansible==4.1.0
+sudo pip install jinja2==3.0.1
```
#### Docker for Mac users
```shell script
sudo easy_install pip
-sudo pip install ansible==2.5.2
-pip install jinja2==2.9.6
+sudo pip install ansible==4.1.0
+pip install jinja2==3.0.1
```
Docker for Mac does not provide any official ways to meet some requirements for OpenWhisk.
You need to depend on the workarounds until Docker provides official methods.
@@ -45,8 +45,8 @@
##### Enable Docker remote API
The remote Docker API is required for collecting logs using the Ansible playbook [logs.yml](logs.yml).
-##### Activate docker0 network
-This is an optional step for local deployment.
+##### Activate docker0 network (local dev only)
+
The OpenWhisk deployment via Ansible uses the `docker0` network interface to deploy OpenWhisk and it does not exist on Docker for Mac environment.
An expedient workaround is to add alias for `docker0` network to loopback interface.
@@ -70,6 +70,16 @@
In all instructions, replace `<openwhisk_home>` with the base directory of your OpenWhisk source tree. e.g. `openwhisk`
+#### Ansible with pyenv (local dev only)
+
+When using [pyenv](https://github.com/pyenv/pyenv) to manage your versions of python, the [ansible python interpreter](https://docs.ansible.com/ansible/latest/reference_appendices/python_3_support.html) will use your system's default python, which may have a different version.
+
+To make sure ansible uses the same version of python which you configured, execute:
+
+```bash
+echo -e "\nansible_python_interpreter: `which python`\n" >> ./environments/local/group_vars/all
+```
+
#### Preserving configuration and log directories on reboot
When using the local Ansible environment, configuration and log data is stored in `/tmp` by default. However, operating
system such as Linux and Mac clean the `/tmp` directory on reboot, resulting in failures when OpenWhisk tries to start
@@ -77,10 +87,12 @@
directory before deploying OpenWhisk.
#### Setup
-
-The following step must be executed once per development environment.
+
+This step should be executed once per development environment.
It will generate the `hosts` configuration file based on your environment settings.
+> This file is generated automatically for an ephemeral CouchDB instance during `setup.yml`.
+
The default configuration does not run multiple instances of core components (e.g., controller, invoker, kafka).
You may elect to enable high-availability (HA) mode by passing tne Ansible option `-e mode=HA` when executing this playbook.
This will configure your deployment with multiple instances (e.g., two Kafka instances, and two invokers).
@@ -98,7 +110,6 @@
db_port=
```
-This file is generated automatically for an ephemeral CouchDB instance during `setup.yml`. If you want to use Cloudant, you have to modify the file.
For convenience, you can use shell environment variables that are read by the playbook to generate the required `db_local.ini` file as shown below.
```shell script
@@ -112,7 +123,7 @@
ansible-playbook -i environments/$ENVIRONMENT setup.yml
```
-Alternatively, if you want to use Cloudant as your datastore:
+##### Use Cloudant as a datastore
```shell script
export OW_DB=Cloudant
@@ -126,7 +137,8 @@
```
#### Install Prerequisites
-This step is not required for local environments since all prerequisites are already installed, and therefore may be skipped.`
+
+> This step is not required for local environments since all prerequisites are already installed, and therefore may be skipped.
This step needs to be done only once per target environment. It will install necessary prerequisites on all target hosts in the environment.
diff --git a/tools/macos/README.md b/tools/macos/README.md
index 41a3cdc..e669a53 100644
--- a/tools/macos/README.md
+++ b/tools/macos/README.md
@@ -26,10 +26,10 @@
The following are required to build and deploy OpenWhisk from a Mac host:
-- [Docker 18.06.3](https://docs.docker.com/docker-for-mac/install/)
-- [Open JDK 10](https://adoptopenjdk.net/releases.html#x64_mac)
-- [Scala 2.11](http://scala-lang.org/download/)
-- [Ansible 2.5.2](https://docs.ansible.com/ansible/latest/installation_guide/intro_installation.html)
+- [Docker 18.06.3+](https://docs.docker.com/docker-for-mac/install/)
+- [Open JDK 11](https://adoptopenjdk.net/releases.html#x64_mac)
+- [Scala 2.12](http://scala-lang.org/download/)
+- [Ansible 4.1.0](https://docs.ansible.com/ansible/latest/installation_guide/intro_installation.html)
**Tips:**
1. Versions of Docker and Ansible are lower than the latest released versions, the versions used in OpenWhisk are pinned to have stability during continuous integration and deployment.<br>
@@ -44,10 +44,10 @@
/usr/bin/ruby -e "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install)"
# install cask
brew tap homebrew/cask
-# install for AdoptOpenJDK (java10)
+# install for AdoptOpenJDK (java11)
brew tap AdoptOpenJDK/openjdk
-# install java 10
-brew install --cask adoptopenjdk10
+# install java 11
+brew install --cask adoptopenjdk11
# install scala
brew install scala
# install gnu tar
@@ -55,7 +55,7 @@
# install pip
sudo easy_install pip
# install script prerequisites
-sudo -H pip install docker==2.2.1 ansible==2.5.2 jinja2==2.9.6 couchdb==1.1 httplib2==0.9.2 requests==2.10.0' | bash
+pip install docker==5.0.0 ansible==4.1.0 jinja2==3.0.1 couchdb==1.2 httplib2==0.19.1 requests==2.25.1 six=1.16.0
```
Make sure you correctly configure the environment variable $JAVA_HOME.
@@ -71,12 +71,47 @@
Follow instructions in [ansible/README.md](../../ansible/README.md)
### Configure the CLI
-Follow instructions in [Configure CLI](../../docs/cli.md)
+
+#### Using brew
+
+```bash
+brew install wsk
+wsk property set --apihost https://localhost
+wsk property set --auth `cat ansible/files/auth.guest`
+```
+#### Other methods
+For more instructions see [Configure CLI doc](../../docs/cli.md).
### Use the wsk CLI
```bash
-bin/wsk action invoke /whisk.system/utils/echo -p message hello --result
+wsk action invoke /whisk.system/utils/echo -p message hello --result
{
"message": "hello"
}
```
+
+# Develop
+
+## Running unit tests
+
+> Unit tests require [Ansible setup](../../ansible/README.md) at the moment.
+
+Bellow are the ansible commands required to prepare your machine:
+
+```bash
+cd ./ansible
+
+ansible-playbook setup.yml -e mode=HA
+ansible-playbook couchdb.yml
+ansible-playbook initdb.yml
+ansible-playbook wipe.yml
+
+ansible-playbook properties.yml
+```
+
+To run the unit tests execute the command bellow from the project's root folder:
+```bash
+# go back to project's root folder
+cd ../
+./gradlew -PtestSetName="REQUIRE_ONLY_DB" :tests:testCoverageLean
+```
\ No newline at end of file
