Update README to reflect the UX changes in Docker App #734

carolinebriaud · 2019-11-12T10:26:38Z

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

- What I did
Update README to reflect the UX changes in Docker App

- How to verify it
Read the README

- A picture of a cute animal (not mandatory)

codecov · 2019-11-12T10:58:16Z

Codecov Report

Merging #734 into master will not change coverage.
The diff coverage is n/a.

@@           Coverage Diff           @@
##           master     #734   +/-   ##
=======================================
  Coverage   68.98%   68.98%           
=======================================
  Files          64       64           
  Lines        3437     3437           
=======================================
  Hits         2371     2371           
  Misses        748      748           
  Partials      318      318

Continue to review full report at Codecov.

Legend - Click here to learn more
Δ = absolute <relative> (impact), ø = not affected, ? = missing data
Powered by Codecov. Last update 61e61a8...c2e6ef4. Read the comment docs.

silvin-lubecki · 2019-11-12T14:52:27Z

README.md

-1. You have several environments where you want to deploy the application, with small configuration differences
-1. You have lots of similar applications
+* Simple management of Docker Apps across different teams and between different environments (Development/QA/Staging/Production)
+* Easy sharing of multi-service applications to container registries (e.g., [Docker Hub](https://hub.docker.com/) or [Docker Trusted Registry](https://docs.docker.com/ee/dtr/)) via multiple Docker images


Why multiple Docker images? 🤔

You're right, I have corrected that.

silvin-lubecki · 2019-11-12T17:04:22Z

README.md

+
+### Writing an App definition
+
+The first step in using Docker App is to write the App definition. This definition can be created (1) from an existing Compose file using the `docker app init` command (2) via  a template from the Application Designer, or (3) from scratch. 


Should we add a link to an official page explaining what is Application Designer?

OK, link added to documentation

silvin-lubecki · 2019-11-12T17:12:14Z

README.md

+
+The App definition is a .dockerapp folder that contains three distinct pieces: metadata, a service list, and the parameters. 
+
+metadata | Includes the App name and version; provides better traceability back to code changes when debugging issues


Did you intend drawing a table here? Because otherwise it looks weird

yes it is supposed to render as a table

I see it is not correctly rendered. Will double check.

silvin-lubecki · 2019-11-12T17:13:09Z

README.md

+
+metadata | Includes the App name and version; provides better traceability back to code changes when debugging issues
+service list | Defined in a Compose file
+parameters | Settings that can be changed when running the App


Should we add "YAML formatted"? as we specify it's a Compose file for service list

I added the .yml extension in the table

silvin-lubecki · 2019-11-12T17:14:03Z

README.md

+The App definition is a .dockerapp folder that contains three distinct pieces: metadata, a service list, and the parameters. 
+
+metadata | Includes the App name and version; provides better traceability back to code changes when debugging issues
+service list | Defined in a Compose file


Add a link to the Compose v3 reference?
[Compose file](https://docs.docker.com/compose/compose-file/)

silvin-lubecki · 2019-11-12T17:18:15Z

README.md

+### Building an App image
+
+Once the App definition is written, the next step is to build the App image from the App definition using the `docker app build` command. With this command you can tag your App image, set build-time variables, or make the build quiet. 
+Note that service images inside of an App image are immutable, meaning that the App version ties to a fixed list of service images (i.e., updating the images inside of a Docker App requires recreating the App image).


requires re-building the App image instead?

Right. Modified.

README.md

silvin-lubecki · 2019-11-12T17:34:29Z

README.md


 ```console
-$ docker app init hello
+$ docker app init --compose-file docker-compose.yml hello
+Created "hello.dockerapp"
 $ ls


You can use the tree command here

$ tree . ├── docker-compose.yml └── voting-app.dockerapp ├── docker-compose.yml ├── metadata.yml └── parameters.yml 1 directory, 4 files

And maybe also add a note that the first docker-compose.yml file is not used anymore?

README.md

chris-crone · 2019-11-13T12:44:00Z

README.md

+* Support for multiple orchestrators (Swarm or Kubernetes)
+* Provides the very same UX flow as the one for Docker images
+* Implements the [CNAB](https://cnab.io) industry standard
+* Offers full support of Docker Contexts


chris-crone · 2019-11-13T12:46:00Z

README.md

+### Building an App image
+
+Once the App definition is written, the next step is to build the App image from the App definition using the `docker app build` command. With this command you can tag your App image, set build-time variables, or make the build quiet. 
+Note that service images inside of an App image are immutable, meaning that the App version ties to a fixed list of service images (i.e., updating the images inside of a Docker App requires rebuilding the App image).


Do we want to say why this is the case? i.e.: as this makes deploying applications more deterministic

chris-crone · 2019-11-13T12:47:04Z

README.md

+
+### Sharing the App on the Hub
+
+You can push any App image already built or pulled to Docker Hub (or any registry) using the `docker app push` command. You can also pull App images from any container registry using the `docker app pull` command.


s/registry/OCI compliant registry/

You can link OCI to https://www.opencontainers.org

chris-crone · 2019-11-13T12:48:38Z

README.md

+
+## Example
+
+Using the [hello-world](https://github.com/docker/app/tree/master/examples/hello-world) application example, we are going to build, share, and run a Docker App that launches an HTTP server that prints the text variable value when hit on the configured port. 


You can replace https://github.com/docker/app/tree/master/examples/hello-world with ./examples/hello-world or examples/hello-world. GitHub markdown supports relative paths.

chris-crone · 2019-11-13T12:50:54Z

README.md

-Removing network hello_default
-```
+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 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.


It would be good to add the positive side of the specification: interoperability and a common storage mechanism

chris-crone · 2019-11-13T12:51:23Z

README.md

-It requires [Docker CLI](https://download.docker.com) 19.03.0 or later with experimental features enabled.
-Either set environment variable `DOCKER_CLI_EXPERIMENTAL=enabled`
-or update your [docker CLI configuration](https://docs.docker.com/engine/reference/commandline/cli/#experimental-features).
+Docker App is a *command line* plugin (not be confused with *docker engine plugins*) that extends the `docker` command with `app` sub-commands. It requires [Docker CLI](https://download.docker.com/) 19.03.0 or later, with experimental features enabled. Either set environment variable `DOCKER_CLI_EXPERIMENTAL=enabled` or update your [docker CLI configuration](https://docs.docker.com/engine/reference/commandline/cli/#experimental-features).


s/It requires/It requires the/

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

chris-crone

LGTM with very minor changes

GordonTheTurtle added the status/0-triage label Nov 12, 2019

rumpl approved these changes Nov 12, 2019

View reviewed changes

silvin-lubecki reviewed Nov 12, 2019

View reviewed changes

carolinebriaud force-pushed the fix-readme branch 2 times, most recently from 9a720b8 to acbaf70 Compare November 12, 2019 15:08

carolinebriaud changed the title ~~[WIP] Update README to reflect the UX changes in Docker App~~ Update README to reflect the UX changes in Docker App Nov 12, 2019

carolinebriaud requested a review from chris-crone November 12, 2019 15:37

silvin-lubecki reviewed Nov 12, 2019

View reviewed changes

README.md Outdated Show resolved Hide resolved

silvin-lubecki reviewed Nov 12, 2019

View reviewed changes

README.md Show resolved Hide resolved

carolinebriaud force-pushed the fix-readme branch 3 times, most recently from 3de9660 to 440a48f Compare November 13, 2019 12:19

chris-crone reviewed Nov 13, 2019

View reviewed changes

Update README to reflect the UX changes in Docker App

c2e6ef4

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

chris-crone approved these changes Nov 13, 2019

View reviewed changes

carolinebriaud force-pushed the fix-readme branch from 440a48f to c2e6ef4 Compare November 13, 2019 12:52

carolinebriaud merged commit 3328d80 into docker:master Nov 13, 2019

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Update README to reflect the UX changes in Docker App #734

Update README to reflect the UX changes in Docker App #734

carolinebriaud commented Nov 12, 2019 •

edited

Loading

codecov bot commented Nov 12, 2019 •

edited

Loading

silvin-lubecki Nov 12, 2019

carolinebriaud Nov 12, 2019

silvin-lubecki Nov 12, 2019

carolinebriaud Nov 13, 2019

silvin-lubecki Nov 12, 2019

carolinebriaud Nov 12, 2019

carolinebriaud Nov 13, 2019

silvin-lubecki Nov 12, 2019

carolinebriaud Nov 13, 2019

silvin-lubecki Nov 12, 2019

carolinebriaud Nov 13, 2019

silvin-lubecki Nov 12, 2019

carolinebriaud Nov 13, 2019

silvin-lubecki Nov 12, 2019

carolinebriaud Nov 13, 2019

chris-crone Nov 13, 2019

carolinebriaud Nov 13, 2019

chris-crone Nov 13, 2019

carolinebriaud Nov 13, 2019

chris-crone Nov 13, 2019 •

edited

Loading

carolinebriaud Nov 13, 2019

chris-crone Nov 13, 2019 •

edited

Loading

carolinebriaud Nov 13, 2019

chris-crone Nov 13, 2019

chris-crone Nov 13, 2019

chris-crone left a comment


		### Writing an App definition

		The first step in using Docker App is to write the App definition. This definition can be created (1) from an existing Compose file using the `docker app init` command (2) via a template from the Application Designer, or (3) from scratch.


		The App definition is a .dockerapp folder that contains three distinct pieces: metadata, a service list, and the parameters.

		metadata \| Includes the App name and version; provides better traceability back to code changes when debugging issues


		### Sharing the App on the Hub

		You can push any App image already built or pulled to Docker Hub (or any registry) using the `docker app push` command. You can also pull App images from any container registry using the `docker app pull` command.


		## Example

		Using the [hello-world](https://github.com/docker/app/tree/master/examples/hello-world) application example, we are going to build, share, and run a Docker App that launches an HTTP server that prints the text variable value when hit on the configured port.

Update README to reflect the UX changes in Docker App #734

Update README to reflect the UX changes in Docker App #734

Conversation

carolinebriaud commented Nov 12, 2019 • edited Loading

codecov bot commented Nov 12, 2019 • edited Loading

Codecov Report

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

chris-crone Nov 13, 2019 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

chris-crone Nov 13, 2019 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

chris-crone left a comment

Choose a reason for hiding this comment

carolinebriaud commented Nov 12, 2019 •

edited

Loading

codecov bot commented Nov 12, 2019 •

edited

Loading

chris-crone Nov 13, 2019 •

edited

Loading

chris-crone Nov 13, 2019 •

edited

Loading