Update README for docker/app/examples.

Fix hello-world example.
Remove cnab-helm example.

Signed-off-by: Caroline Briaud <caroline.briaud@docker.com>

examples/README.md

@@ -1,28 +1,19 @@
 ## Examples
 
-This folder contains several examples of applications built using Docker
-Application, from a simple `hello-world` application to more complex,
-multi-service applications.
+This is a collection of [Docker App](./README.MD) examples. Most of them are fairly simple, and intended to illustrate various aspects of the Docker App product.
 
-### [Hello world!](hello-world)
+### [Hello World: Starting example](hello-world)
 
-Learn how the basics of how to write a simple Docker Application.
+Learn how to write your first Docker App.
 
-### [Convert an existing Compose file](voting-app)
+### [Voting App: Bootstraping a Docker App from an existing Compose file](voting-app)
 
-Learn how to create a Docker Application from an existing Compose file using the
-Docker voting app from [Docker samples](https://github.com/dockersamples).
+Learn how to create a Docker App having multiple services from an existing Compose file.
 
-### [Build service containers and package application](dockercoins)
+### [Docker Coins: Build service images](dockercoins)
 
-Learn how to organize your application so docker app will build the services docker images and the application image.
+Learn how Docker App can build the service images along with the App image.
 
-### [Docker Application CNAB generation](cnab-simple)
+### [CNAB Simple: Starting example for CNAB](cnab-simple)
 
-Create a [CNAB](https://cnab.io) `bundle.json` and invocation image from a
-Docker Application.
-
-### [Deploy a Helm Chart CNAB using Docker App](cnab-helm)
-
-As Docker App is a [CNAB](https://cnab.io) compliant client, you can deploy any
-CNAB.
+Create a [CNAB](https://cnab.io) bundle and an invocation image from a Docker App.

examples/hello-world/README.md

@@ -1,18 +1,31 @@
-## Hello world!
+# Example: Hello World
 
-### Initialize project
-
-In this example, we will create a single service application that deploys a web
+In this example, we will create a Docker App which is a single service application deploying a web
 server with a configurable text message.
 
-First, we will initialize the project.
+## Creating an App definition
+
+First, we create an App definition using the `docker app init` command:
 
-```console
+```shell
 $ docker app init hello-world
-$ ls -l
--rw-r--r-- 1 README.md
-drw-r--r-- 1 example-hello-world.dockerapp
-$ cat hello-world.dockerapp/metadata.yml
+Created "hello-world.dockerapp"
+$ tree
+.
+├── hello-world.dockerapp
+    ├── docker-compose.yml
+    ├── metadata.yml
+    └── parameters.yml
+```
+
+A new folder named `hello-world.dockerapp` now exists, which contains three YAML documents:
+* metadata
+* a [Compose file](https://docs.docker.com/compose/compose-file/)
+* parameters to be used at runtime
+
+The `metadata.yml` file should display as follows:
+
+```yaml
 # Version of the application
 version: 0.1.0
 # Name of the application
@@ -23,111 +36,135 @@ description:
 maintainers:
   - name: user
     email:
+```
+
+The `docker-compose.yml` should contain the following:
 
-$ cat hello-world.dockerapp/services.yml
-# This section contains the Compose file that describes your application services.
+```yaml
 version: "3.6"
 services: {}
-
-$ cat hello-world.dockerapp/parameters.yml
 ```
 
+The `parameters.yml`file should be empty.
+
+## Editing App definition
+
 Open `hello-world.dockerapp` with your favorite text editor.
 
-### Edit metadata
+### Editing the metadata
 
-Edit the `description` and `maintainers` fields in the metadata section.
+Open the `metadata.yml` file and edit the `description` and `maintainers` fields in the metadata section.
 
-### Edit the services
+### Editing the list of services
 
-Add a service `hello` to the `services` section.
+Open the `docker-compose.yml` file and add a `hello` service to the `services` section.
 
 ```yaml
-[...]
 version: "3.6"
 services:
   hello:
     image: hashicorp/http-echo
     command: ["-text", "${text}"]
     ports:
       - ${port}:5678
-
-[...]
 ```
 
-### Edit the parameters
+### Editing the parameters
 
-In the parameters section, add every variables with the default value you want,
-e.g.:
+In the `parameters.yml` file, add variables with their default value:
 
 ```yaml
-[...]
 port: 8080
 text: Hello, World!
 ```
 
-### Inspect
-
-Inspecting a Docker Application gives you a summary of what the application
-includes.
+## Building an App image
 
-```console
-$ docker app inspect hello-world.dockerapp
-hello-world 0.1.0
+Next, build an App image from the App definition we have created:
 
-Maintained by: user <user@email.com>
-
-Hello, World!
+```shell
+$ docker app build . -f hello-world.dockerapp -t myrepo/hello:0.1.0
+[+] Building 0.6s (6/6) FINISHED
+(...) (Build output)
+sha256:7b48c121fcafa0543b7e88c222304f9fada9911011694b041a7f0e096536db6c
+```
 
-Service (1) Replicas Ports Image
------------ -------- ----- -----
-hello       1        8080  hashicorp/http-echo
+At this point, an App image with the `myrepo/hello:1.0.1` tag has been built from the `hello-world.dockerapp` App definition. This immutable App image includes all the service images at fixed versions that you can run or share.
 
-Parameters (2) Value
--------------- -----
-port           8080
-text           Hello, World!
-```
+## Inspecting an App image
 
-### Install
+Now let's get detailed information about the App image we just built using the `docker app image inspect` command. Note that the `--pretty` option allows to get a human friendly output rather than the JSON default output.
 
-You directly install your application by running
-`docker app deploy --set text="Hello user!"`.
+```shell
+$ docker  app image inspect myrepo/hello-world:0.1.0 --pretty
+version: 0.1.0
+name: hello-world
+description: This is an Hello World example
+maintainers:
+- name: user
+  email: user@email.com
 
-Navigate to `http://<ip_of_your_node>:8080` with a web browser and you will see
-the text message. Note that `<ip_of_your_node>` is `127.0.0.1` if you installed
-to your local Docker endpoint.
+SERVICE   REPLICAS   PORTS   IMAGE
+hello     1          8080    docker.io/hashicorp/http-echo:latest@sha256:ba27d460cd1f22a1a4331bdf74f4fccbc025552357e8a3249c40ae216275de96
 
-```console
-$ curl 127.0.0.1:8080
-Hello user!
+PARAMETER VALUE
+port      8080
+text      Hello, World!
 ```
 
-### Push
+## Sharing the App
 
-You can share your application by pushing it to a container registry such as
-the Docker Hub.
+Share your App image by pushing it to a container registry such as Docker Hub.
 
-```console
-$ docker app push hello-world --tag myrepo/hello-world:0.1.0
+```shell
+$ docker app push myrepo/hello:0.1.0
 ```
 
-You can then use your application package directly from the repository:
+## Running the App
 
-```console
-$ docker app inspect myrepo/hello-world:0.1.0
-hello-world 0.1.0
+Now run your App:
 
-Maintained by: user <user@email.com>
+```shell
+$ docker app run myrepo/hello:0.1.0  --name myhelloworld
+Creating network myhelloworld_default
+Creating service myhelloworld_hello
+App "myhelloworld" running on context "default"
+```
 
-Hello, World!
+You can specify the Docker endpoint where an application is installed using a context. By default, your App will run on the currently active context. You can select another context with the docker context use command, and the docker app run command will thereafter run your app on this particular context.
 
-Service (1) Replicas Ports Image
------------ -------- ----- -----
-hello       1        8080  myrepo/hello-world@sha256:ba27d460cd1f22a1a4331bdf74f4fccbc025552357e8a3249c40ae216275de96
+Next, you can check the list of running Apps:
 
-Parameters (2) Value
--------------- -----
-port           8080
-text           Hello, World!
+```shell
+$ docker app ls
+INSTALLATION   APPLICATION         LAST ACTION   RESULT    CREATED              MODIFIED             REFERENCE
+myhelloworld   hello-world (0.1.0) install       success   About a minute ago   About a minute ago   docker.io/myrepo/hello-world:0.1.0
 ```
+
+## Inspecting a running App
+
+Finally you can get detailed information about a running App using the `docker app inspect` command. Note that the `--pretty` option allows to get a human friendly output rather than the JSON default output.
+
+```shell
+$ docker app inspect myhelloworld --pretty
+Installation:
+  Name: myhelloworld
+  Created: 3 minutes ago
+  Modified: 3 minutes ago
+  Revision: 01DSQMWWABCM27K3FWSCES3H76
+  Last Action: install
+  Result: success
+  Ochestrator: swarm
+
+Application:
+  Name: hello-world
+  Version: 0.1.0
+  Image Reference: docker.io/myrepo/hello-world:0.1.0
+
+Parameters:
+  port: "8080"
+  text: Hello, World!
+
+ID            NAME                MODE        REPLICAS  IMAGE                PORTS
+mocfqnkadxw3  myhelloworld_hello  replicated  1/1       hashicorp/http-echo  *:8080->5678/tcp
+```

examples/hello-world/example-hello-world.dockerapp/metadata.yml

@@ -3,7 +3,7 @@ version: 0.1.0
 # Name of the application
 name: hello-world
 # A short description of the application
-description: "Hello, World!"
+description: "This is an Hello World example"
 # List of application maintainers with name and email for each
 maintainers:
   - name: user