example: Add details and format

Signed-off-by: Christopher Crone <christopher.crone@docker.com>
Signed-off-by: Nicolas De Loof <nicolas.deloof@gmail.com>

ecs/demo/README.md

@@ -1,107 +0,0 @@
-## Compose sample application
-
-### Python/Flask application
-
-```
-+--------------------+              +------------------+
-|                    |              |                  |
-|    Python Flask    |  timestamps  |      Redis       |
-|    Application     |------------->|                  |
-|                    |              |                  |
-+--------------------+              +------------------+
-```
-
-### Things you'll need to do.
-
-There are a number of places you'll need to fill in information. You can find them with:
-
-```
-grep -r '<<<' ./*
-./docker-compose.yml:    x-aws-pull_credentials: <<<your arn for your secret you can get with docker ecs secret list>>>
-./docker-compose.yml:    image: <<<yourhubname>>>/timestamper
-## Walk through
-```
-
-### Setup pull credentials for private Docker Hub repositories
-
-You should use a Personal Access Token (PAT) vs your default password. If you have 2FA enabled on your Hub account you will have to create a PAT. You can read more about managing access tokens here: https://docs.docker.com/docker-hub/access-tokens/
-
-```
-  docker ecs secret create -d MyKey -u myhubusername -p myhubpat
-```
-
-### Create an AWS Docker context and list available contexts
-
-```
-docker ecs setup
-Enter context name: aws
-✔ sandbox.devtools.developer
-Enter cluster name:
-Enter region: us-west-2
-✗ Enter credentials:
-
-docker context ls
-NAME                DESCRIPTION                               DOCKER ENDPOINT               KUBERNETES ENDPOINT   ORCHESTRATOR
-aws
-default *           Current DOCKER_HOST based configuration   unix:///var/run/docker.sock                         swarm
-```
-
-### Test locally
-
-```
-docker context use default
-docker-compose up
-open http://localhost:5000
-```
-
-### Push images to hub for ecs (ecs cannot see your local image cache)
-
-```
-docker-compose push
-```
-
-### Switch to ECS context and launch the app
-
-```
-docker context use aws
-docker ecs compose up
-```
-
-### Check out the CLI
-
-```
-docker ecs compose ps
-docker ecs compose logs
-```
-
-### Check out the aws console
-
-- cloud formation
-- cloud watch
-- security groups
-- Load balancers (ELB for this example / ALB if your app only uses 80/443)
-
-### Checkout cloudformation
-
-```
-docker ecs compose convert
-```
-
-### Stop the meters
-
-```
-docker ecs compose down
-
-```
-
-## Using Amazon ECR instead of Docker Hub
-
-[Makefile](Makefile) has an example setup for creating an ECR repository and pushing to it. You'll need to have the AWS CLI installed and your AWS credentials available.
-
-```
-make create-ecr
-REGISTRY_ID=<from the create above> make build-image
-REGISTRY_ID=<from the create above> make push-image-ecr
-```
-
-If you want to use this often, you'll likely want to replace `PUT_ECR_REGISTRY_ID_HERE` with the value from above.

ecs/example/README.md

@@ -0,0 +1,178 @@
+## Compose sample application
+
+This sample application was demoed as part of the AWS Cloud Containers
+Conference on 2020-07-09. It has been tested on Linux and macOS.
+
+Note that `$` is used to denote commands in blocks where the command and its
+output are included.
+
+### Python/Flask application
+
+```
++--------------------+              +------------------+
+|                    |              |                  |
+|    Python Flask    |  timestamps  |      Redis       |
+|    Application     |------------->|                  |
+|                    |              |                  |
++--------------------+              +------------------+
+```
+
+### Things you'll need to do
+
+There are a number of places you'll need to fill in information.
+You can find them with:
+
+```console
+$ grep -r '<<<' ./*
+./docker-compose.yml:    x-aws-pull_credentials: <<<your arn for your secret you can get with docker ecs secret list>>>
+./docker-compose.yml:    image: <<<your docker hub user name>>>/timestamper
+## Walk through
+```
+
+### Setup pull credentials for private Docker Hub repositories
+
+You should use a Personal Access Token (PAT) rather than your account password.
+If you have 2FA enabled on your Hub account you will need to create a PAT.
+You can read more about managing access tokens here:
+https://docs.docker.com/docker-hub/access-tokens/
+
+```console
+docker ecs secret create -d MyKey -u myhubusername -p myhubpat
+```
+
+### Create an AWS Docker context and list available contexts
+
+To initialize the Docker ECS integration, you will need to run the `setup`
+command. This will create a Docker context that works with AWS ECS.
+
+```console
+$ docker ecs setup
+Enter context name: aws
+✔ sandbox.devtools.developer
+Enter cluster name:
+Enter region: us-west-2
+✗ Enter credentials:
+```
+
+You can verify that the context was created by listing your Docker contexts:
+
+```console
+$ docker context ls
+NAME                DESCRIPTION                               DOCKER ENDPOINT               KUBERNETES ENDPOINT   ORCHESTRATOR
+aws
+default *           Current DOCKER_HOST based configuration   unix:///var/run/docker.sock                         swarm
+```
+
+### Test locally
+
+The first step is to test your application works locally. To do this, you will
+need to switch to using the default local context so that you are targeting your
+local machine.
+
+```console
+docker context use default
+```
+
+You can then run the application using `docker-compose`:
+
+```console
+docker-compose up
+```
+
+Once the application has started, you can navigate to http://localhost:5000
+using your Web browser using the following command:
+
+```console
+open http://localhost:5000
+```
+
+### Push images to Docker Hub for ECS (ECS cannot see your local image cache)
+
+In order to run your application in the cloud, you will need your container
+images to be in a registry. You can push them from your local machine using:
+
+```console
+docker-compose push
+```
+
+You can verify that this command pushed to the Docker Hub by
+[logging in](https://hub.docker.com) and looking for the `timestamper`
+repository under your user name.
+
+### Switch to ECS context and launch the app
+
+Now that you've tested the application works locally and that you've pushed the
+container images to the Docker Hub, you can switch to using the `aws` context
+you created earlier.
+
+```console
+docker context use aws
+```
+
+Running the application on ECS is then as simple as doing a `compose up`:
+
+```console
+docker ecs compose up
+```
+
+### Check out the CLI
+
+Once the application is running in ECS, you can list the running containers with
+the `ps` command. Note that you will need to run this from the directory where
+you Compose file is.
+
+```console
+docker ecs compose ps
+```
+
+You can also read the application logs using `compose logs`:
+
+```console
+docker ecs compose logs
+```
+
+### Check out the AWS console
+
+You can see all the AWS components created for your running application in the
+AWS console. There you will find:
+
+- CloudFormation being used to manage all the infrastructure
+- CloudWatch for logs
+- Security Groups for network policies
+- Load balancers (ELB for this example / ALB if your app only uses 80/443)
+
+### Checkout CloudFormation
+
+The ECS Docker CLI integration has the ability to output the CloudFormation
+template used to create the application in the `compose convert` command. You
+can see this by running:
+
+```console
+docker ecs compose convert
+```
+
+### Stop the meters
+
+To shut down your application, you simply need to run:
+
+```console
+docker ecs compose down
+```
+
+## Using Amazon ECR instead of Docker Hub
+
+If you'd like to use AWS ECR instead of Docker Hub, the [Makefile](Makefile) has
+an example setup for creating an ECR repository and pushing to it.
+You'll need to have the AWS CLI installed and your AWS credentials available.
+
+```console
+make create-ecr
+REGISTRY_ID=<from the create above> make build-image
+REGISTRY_ID=<from the create above> make push-image-ecr
+```
+
+Note that you will need to change the name of the image in the
+[Compose file](docker-compose.yml).
+
+If you want to use this often, you'll likely want to replace
+`PUT_ECR_REGISTRY_ID_HERE` with the value from above.

ecs/example/docker-compose.yml

@@ -3,7 +3,7 @@ services:
   frontend:
     build: app
     x-aws-pull_credentials: <<<your arn for your secret you can get with docker ecs secret list>>>
-    image: <<<yourhubname>>>/timestamper
+    image: <<<your docker hub user name>>>/timestamper
     ports:
       - "5000:5000"
     depends_on: