Merge pull request #754 from carolinebriaud/fix-example-next

Update CNAB-simple example to reflect the UX changes
docker · Nov 20, 2019 · 355ab4f · 355ab4f
2 parents 6c2b173 + ede60f1
commit 355ab4f
Show file tree

Hide file tree

Showing 5 changed files with 119 additions and 44 deletions.
diff --git a/examples/README.md b/examples/README.md
@@ -1,6 +1,6 @@
 ## Examples
 
-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.
+This is a collection of Docker App examples. Most of them are fairly simple, and intended to illustrate various aspects of the Docker App product.
 
 ### [Hello World: Starting example](hello-world)
 

diff --git a/examples/cnab-simple/README.md b/examples/cnab-simple/README.md
@@ -1,60 +1,127 @@
-# Docker Application to CNAB
+# Example: From Docker App to CNAB
 
-### Requirements
+Docker Apps are Docker’s implementation of the industry standard Cloud Native Application Bundle (CNAB). [CNAB](https://cnab.io/) is an industry specification put in place to facilitate the bundling, sharing, installing and managing of cloud-native apps that are not only made up of containers but also from such things as hosted databases, functions, etc.
 
-* [Docker Desktop](https://www.docker.com/products/docker-desktop) with Kubernetes enabled or any other Kubernetes cluster
-* Source code from this directory
+Docker App is designed to abstract as many CNAB specifics as possible, to provide users with a tool that is easy to use while alleviating the need to bother with the CNAB specification. 
 
-### Examples
+This example will demonstrate that Docker App is actually leveraging CNAB. To learn more about CNAB, you can refer to the [CNAB specification](https://github.com/cnabio/cnab-spec).
 
-Show the details of the application with `inspect`
 
-```console
-$ docker app inspect
-hello 0.2.0
+## App Definition
 
-Maintained by: garethr <someone@example.com>
+The App definition for this example is ready to use and can be found in the [hello.dockerapp](hello.dockerapp) directory in this folder.
 
-Sample app for DockerCon EU 2018
 
-Service (1) Replicas Ports Image
------------ -------- ----- -----
-hello       1        8765  hashicorp/http-echo:0.2.3
+## App Image
 
-Parameters (2) Value
--------------- -----
-port           8765
-text           Hello DockerCon!
+Now we are going to build an App image from this App definition.
+
+```shell
+$ docker app build . -f hello.dockerapp -t myrepo/cnab-example:1.0.0
+[+] Building 0.6s (6/6) FINISHED
+(...) (Build output)
+sha256:ee61121d6bff0266404cc0077599c1ef7130289fec721
+```                                                                              
+
+*Note that a `bundle.json` file has been created in the `~/.docker/app/bundles/docker.io/myrepo/cnab-example/_tags/1.0.0` directory.*
+
+Open the open the `bundle.json` file in your favorite text editor and you'll see this is a [CNAB bundle](https://github.com/cnabio/cnab-spec).
+
+Copy the `bundle.json`file to your working directory, next to the `hello.dockerapp` App definition.
+
+```shell
+$ tree
+.
+├── bundle.json
+└── hello.dockerapp
+    ├── docker-compose.yml
+    ├── metadata.yml
+    └── parameters.yml
 ```
 
-Install the application:
+## Running App
 
-```console
-$ docker app install
+### Run the App from an App image
+
+You can run this App using the `docker app run`command.
+
+```shell
+$ docker app run myrepo/cnab-example:1.0.0 --name mycnabexample
+Creating network mycnabexample_default
+Creating service mycnabexample_hello
+App "mycnabexample" running on context "default"
 ```
 
-Update the installation, demonstrating setting parameters:
+Get the list of running Apps using the `docker app ls` command.
 
-```console
-$ docker app update --set port=9876 --set text="hello DockerCon EU" hello
+```shell
+$ docker app ls
+RUNNING APP       APP NAME        LAST ACTION  RESULT   CREATED         MODIFIED          REFERENCE
+mycnabexample     hello (0.2.0)   install      success  15 minutes ago  15 minutes ago    docker.io/myrepo/cnab-example:1.0.0
 ```
 
-Uninstall the application installation:
+Then remove the current running App.
 
-```console
-$ docker app uninstall hello
+```shell
+$ docker app rm mycnabexample
+Removing service mycnabexample_hello
+Removing network mycnabexample_default
 ```
 
-Demonstrate building a `bundle.json` for CNAB.
-
-```console
-$ docker app bundle
-Invocation image "hello:0.2.0-invoc" successfully built
-$ cat bundle.json
-{
-  "name": "hello",
-  "version": "0.2.0",
-  "description": "Sample app for DockerCon EU 2018",
-  ...
-}
+### Run the App from a CNAB bundle
+
+To demonstrate that Docker App is an implementation of [CNAB](https://cnab.io/), it is also possible to directly run the `bundle.json` file (or any other CNAB bundle) using the `--cnab-bundle-json` experimental flag. 
+
+*Note: To use this flag, you have to enable the experimental mode for the Docker CLI first.*
+
+Open the `~/.docker/config.json` file in a text editor and change the `"experimental"` field to `"enabled"`.
+
+Run your app passing a `bundle.json` file.
+
+```shell
+$ docker app run myrepo/cnab-example:1.0.0 --name mycnabexample --cnab-bundle-json bundle.json
+Creating network mycnabexample_default
+Creating service mycnabexample_hello
+App "mycnabexample" running on context "default"
+```
+
+Get the list of running Apps using the `docker app ls` command.
+
+```shell
+$ docker app ls
+RUNNING APP       APP NAME        LAST ACTION  RESULT   CREATED         MODIFIED          REFERENCE
+mycnabexample     hello (0.2.0)   install      success  15 minutes ago  15 minutes ago    docker.io/myrepo/cnab-example:1.0.0
 ```
+
+Inspect your running app using the `docker app inspect`command.
+
+```shell
+$ docker app inspect mycnabexample --pretty
+Running App:
+  Name: mycnabexample
+  Created: 1 minute ago
+  Modified: 1 minute ago
+  Revision: 01DT28SRQZF12FN5YFQ36XCBYS
+  Last Action: install
+  Result: success
+  Ochestrator: swarm
+
+App:
+  Name: hello
+  Version: 0.2.0
+
+Parameters:
+  port: "8765"
+  text: Hello!
+
+ID           NAME                  MODE         REPLICAS   IMAGE                  PORTS
+c21wxj9ts08y mycnabexample_hello   replicated   1/1        hashicorp/http-echo    *:8765->5678/tcp
+```
+
+Finally, remove the current running App.
+
+```shell
+$ docker app rm mycnabexample
+Removing service mycnabexample_hello
+Removing network mycnabexample_default
+```
diff --git a/examples/cnab-simple/hello.dockerapp/metadata.yml b/examples/cnab-simple/hello.dockerapp/metadata.yml
@@ -1,6 +1,6 @@
 version: 0.2.0
 name: hello
-description: Sample app for DockerCon EU 2018
+description: Hello world example
 maintainers:
-  - name: garethr
+  - name: user
     email: someone@example.com
diff --git a/examples/cnab-simple/hello.dockerapp/parameters.yml b/examples/cnab-simple/hello.dockerapp/parameters.yml
@@ -1,2 +1,2 @@
 port: 8765
-text: Hello DockerCon!
+text: Hello World!
diff --git a/examples/hello-world/README.md b/examples/hello-world/README.md
@@ -167,4 +167,12 @@ Parameters:
 
 ID            NAME                MODE        REPLICAS  IMAGE                PORTS
 mocfqnkadxw3  myhelloworld_hello  replicated  1/1       hashicorp/http-echo  *:8080->5678/tcp
-```
+```
+
+Finally, remove the current running App using the `docker app rm`command.
+
+```shell
+$ docker app rm myhelloworld
+Removing service myhelloworld_hello
+Removing network myhelloworld_default
+```