diff --git a/examples/README.md b/examples/README.md index aa87e64ef..cad02df8c 100644 --- 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 index d548d7a34..e1d963f1b 100755 --- 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 +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 `/Users/username/.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 `/Users/username/.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: titi + 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 +``` \ No newline at end of file diff --git a/examples/cnab-simple/hello.dockerapp/metadata.yml b/examples/cnab-simple/hello.dockerapp/metadata.yml index a2bf11528..4e2d094a1 100644 --- 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 index faf993315..7ffea9dcf 100644 --- 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! \ No newline at end of file +text: Hello World! \ No newline at end of file