This is an automated email from the ASF dual-hosted git repository.
dragos pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/openwhisk.git
The following commit(s) were added to refs/heads/master by this push:
new afe3986 Docs update for local dev (#5134)
afe3986 is described below
commit afe39860eb456b8d32bdd68ed724967aefca72c5
Author: ddragosd <[email protected]>
AuthorDate: Fri Jun 11 12:12:54 2021 -1000
Docs update for local dev (#5134)
---
ansible/README.md | 34 ++++++++++++++++++++-----------
tools/macos/README.md | 55 +++++++++++++++++++++++++++++++++++++++++----------
2 files changed, 68 insertions(+), 21 deletions(-)
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 @@ If you want to deploy OpenWhisk locally using Ansible, you
first need to install
#### 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 @@ If you prefer
[Docker-machine](https://docs.docker.com/machine/) to [Docker for
##### 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 @@ use `-i environments/docker-machine`.
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 @@ up again. To avoid this problem, export the
`OPENWHISK_TMP_DIR` variable assigni
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_host=
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 @@ export OW_DB_PORT=<your couchdb port>
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 @@ ansible-playbook -i environments/$ENVIRONMENT setup.yml
```
#### 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 @@ If you prefer to use Docker-machine, you can follow
instructions in [docker-mach
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 @@ echo '
/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 @@ brew install gnu-tar
# 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 @@ cd /your/path/to/openwhisk
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
