Update documentation

Update README.md and docker-compose.yml

Signed-off-by: Scott Lowe <[email protected]>

README.md

@@ -1,46 +1,57 @@
 # A Simple Flask Web Service
 
-A simple but flexible Flask web service used to demonstrate microservices architectures.
+A simple but flexible Flask web service used to demonstrate microservices architectures. It is designed to operate across three different containers:
+
+* A "front-end" container that provides an HTML response based on information gathered from two "back-end" JSON-based web services
+* The "users" API, which is a JSON-based web service queried by the front-end container(s)
+* The "orders" API, which is a JSON-based web service queried by the front-end container(s)
 
 ## Usage
 
-This web service does nothing other than respond, either in HTML or JSON, with information about the web request, the system making the request, and the system handling the request.
+This web service is a single application designed to run in three separate containers.
+
+### Using Docker Compose
 
-To run the web service, simply execute the Python script in the `app` directory, like this:
+The easiest way to spin up the application is to use Docker Compose. A `docker-compose.yml` file is provided in the repository.
 
 ```
-python app/main.py
+docker-compose up -d
 ```
 
-Or, as a Docker container:
+### Running the Containers Manually
 
-```
-docker run -d -p 5000:5000 slowe/flask-web-svc:latest
-```
+Running the containers manually is a bit more difficult, but certainly possible.
 
-Specify the `PORT` environment variable to have the web service listen on a port _other_ than 5000, like this:
+1. First, launch the "users" API container:
 
-```
-PORT=7000 python app/main.py
-```
+        docker run -d -e PORT=6000 -p 6000:6000 slowe/flask-web-svc:latest
 
-Or, when using a Docker container:
+    Make note of the IP address where the container is running, as you'll need it later.
 
-```
-docker run -d -e PORT=7000 -p 7000:7000 slowe/flask-web-svc:latest
-```
+2. Next, launch the "orders" API container:
 
-Once the application is running, make web requests to it (using `curl` or a web browser). _Any_ top-level URL is supported, and will all return the same information. Assuming you have the application listening on port 5000 on IP address 192.168.99.100, these requests would all return a valid HTML response:
+        docker run -d -e PORT=7000 -p 7000:7000 slowe/flask-web-svc:latest
 
-```
-http://192.168.99.100:5000/auth
-http://192.168.99.100:5000/api
-http://192.168.99.100:5000/test
-```
+    As with the previous step, make note of the IP address where this container is scheduled.
+
+3. Before proceeding, ensure that the back-end containers are working properly. Use `curl` or a web browser to access the URL for the containers:
+
+        http://<IP address from step 1>:6000/users/json/
+        http://<IP address from step 2>:7000/users/json/
+
+    You should get back a JSON-formatted response that contains information about the request. If this doesn't work, resolve the issue before continuing.
+
+4. Finally, launch the front-end container:
+
+        docker run -d -e USER_API_HOST=<IP address from step 1> -e USER_API_PORT=6000 -e ORDER_API_HOST=<IP address from step 2> -e ORDER_API_PORT=7000 -p 5000:5000 slowe/flask-web-svc:latest
+
+    If you want the front-end container to listen on a port _other_ than 5000, change the `-p` parameter and add an additional environment parameter in the form `-e PORT=<desired port>`.
+
+The application is now running and ready to use. You can use `curl` or a web browser to access the application:
 
-The web service will **not** respond to multi-level paths, like `/auth/user` or `/api/object`. Only a single-level path is currently supported.
+    http://<IP address from step 4>:5000/
 
-Appending `/json` to the URL will cause the web service to respond in JSON instead of HTML.
+This will provide an HTML-formatted response that contains information about the request and the requests/responses from the back-end JSON-based web services. You can use this information to see how various container orchestration systems and other technologies affect the communications between containers.
 
 ## License
 

docker-compose.yml

@@ -1,22 +1,22 @@
 version: "2"
 services:
   web-ui:
-    image: newver-14
+    image: slowe/flask-web-svc:0.4
     ports:
       - "5000:5000"
     environment:
-      - USER_API_HOST=192.168.99.100
+      - USER_API_HOST=user-api
       - USER_API_PORT=6000
-      - ORDER_API_HOST=192.168.99.100
+      - ORDER_API_HOST=order-api
       - ORDER_API_PORT=7000
   user-api:
-    image: newver-14
+    image: slowe/flask-web-svc:0.4
     ports:
       - "6000:6000"
     environment:
       - PORT=6000
   order-api:
-    image: newver-14
+    image: slowe/flask-web-svc:0.4
     ports:
       - "7000:7000"
     environment: