Closes eyeezzi#1

The problem was a version incompatibility. fluentd v1.4-2 now requires specifying a ‘root’ user in the log-shipper Dockerfile.

Also updated readmes for clarity.

Author: Uzziah Eyee

README.md

@@ -4,38 +4,40 @@ Monitoring containerized microservices with a centralized logging architecture.
 
 ## Dependencies
 
-- Docker Compose v1.22.0
+- Docker Compose v1.23.2
 
 ## Setup
 
-1. For each microservice, rename `example.env` to `.env` and supply the needed secrets.
+1. Signup with an ELK SaaS provider like [Logz.io](logz.io) to obtain an authentication token. Then for each microservice, rename `example.env` to `.env` and supply the needed secrets.
 
-		docker-compose up -d
-		
-2. Then log into [Logz.io](logz.io) or your preferred ELK SaaS to view your microservices logs.
+2. Run the following commands.
 
+		docker-compose build --pull
+		docker-compose up -d --force-recreate
+		
+3. Then log into your ELK SaaS and view your microservices logs.
 
 ## Project Documentation
 
 ### System Architecture
 
 ![](docs/container-architecture.svg)
 
-I wrote an accompanying [Medium article]() detailing the rationale for this architecture.
+I wrote an accompanying [article](https://hackernoon.com/monitoring-containerized-microservices-with-a-centralized-logging-architecture-ba6771c1971a) explaining this architecture.
 
-## Developer Notes
+## Notes
 
 ### Docker Networking
 
-Containers run isolated by default. For them to comunicate with one another, you need to place them on the same network. We do this using Docker Compose
+By default each containerized process runs in an isolated network namespace. For inter-container communication, place them in the same network namespace...as seen in *docker-compose.yml*.
 
 ### Best practices
 
-1. You can pass secrets for a microservice using the `env_file` attribute in `docker-compose.yml`
-2. Microservices can communicate using their service names if they are in the same docker `network`
+1. You can pass secrets for a microservice using the `env_file` attribute in *docker-compose.yml*.
+2. Microservices can communicate using their service names if they are in the same docker network.
+
+### Improvement Considerations
 
-### Known issues
+1. **Name Duplication:** The value of the `API_SERVER_ADDRESS` variable in *user-simulator/.env* depends on the service name `api-server` specified in *docker-compose.yml*. If we rename the service, we must also change the variable. Is there a way to make this DRY?
 
-1. Some values like service hostnames are specified in 2 places: the docker-compose file, and the service-specific .env file (like for the API BaseURL)
-2. You have to install a plugin for the ELK-service (logz.io) in the fluentd shipper container
-3. Then you have to configure fluentd plugin with your credentials from the ELK service.
+2. In the log-shipper container, I had to install a logz.io-specific plugin. Can't this step be eliminated since fluentd is capable of connecting to https endpoints without plugins?

api-server/README.md

@@ -1,17 +1,16 @@
-## Commands for running app in container
+## Running app in standalone container
 
-1. Build image from *Dockerfile*
+1. Build and run image.
 
-		docker build -t eyeezzi/horus-api-server .
-		
-2. Start container from image. Note the *public:internal* port mapping
+		docker build --no-cache -t eyeezzi/horus-api-server .
+		docker run -d --env-file=.env -p 5000:80 eyeezzi/horus-api-server
 
-		docker run -d -p 5000:80 eyeezzi/horus-api-server
+	> Note: The server runs on port `80`, but we expose it as `5000` on the host in order to avoid privilege issues with binding to low number ports. Knowledge bit: [port-mapping cannot be set in dockerfile.](https://stackoverflow.com/questions/36153025/is-it-possible-to-set-docker-port-mappings-to-host-in-dockerfile)
 
-3. Get the container ID and verify port mapping
+2. View the logs generated by the app
 
 		docker ps
+		docker logs -f <container-name>
 
-4. Tail the logs from the container
-
-		docker logs -f <CONTAINER_ID>
+		# From another terminal on the host machine, test the server
+		curl http://localhost:5000/api/v1/tokens

log-shipper/Dockerfile

@@ -1,8 +1,10 @@
-# Aparently the onbuild variant is better for customization, sadly, it is errors on build.
-FROM fluent/fluentd:v0.12
+FROM fluent/fluentd:v1.4-2
 
-# We need to install a plugin for logz.io output :(
-RUN apk add --update --virtual .build-deps \
+# Use root account to use apk
+USER root
+
+# We need to install a plugin for logz.io output
+RUN apk add --no-cache --update --virtual .build-deps \
         sudo build-base ruby-dev \
  && sudo gem install \
         fluent-plugin-logzio \
@@ -13,5 +15,8 @@ RUN apk add --update --virtual .build-deps \
 
 # Then copy-over our custom config file
 COPY fluentd.conf /fluentd/etc/
+ENV FLUENTD_CONF="fluentd.conf"
+
+USER fluent
 
-ENV FLUENTD_CONF="fluentd.conf"
+# reference: https://hub.docker.com/r/fluent/fluentd

log-shipper/README.md

@@ -0,0 +1,14 @@
+## Notes
+
+### Local setup
+
+1. Build and run the container.
+
+		docker build --no-cache -t eyeezzi/horus-log-shipper .
+		docker run -d --env-file=.env eyeezzi/horus-log-shipper
+		// tail the logs to see any incoming messages
+		docker logs -f <container-name>
+
+2. From another terminal test sending logs to the shipper. You should see the new incoming message in the log tail and also on your ELK SaaS dashboard.
+
+		curl -X POST -H "Content-Type: application/json" -d '{"msg":"this is a test message"}' http://localhost:24224

log-shipper/fluentd.conf

@@ -16,15 +16,15 @@
 	output_include_tags true
 	http_idle_timeout 10
 	<buffer>
-			@type memory
-			flush_thread_count 4
-			flush_interval 3s
-			chunk_limit_size 16m      # Logz.io bulk limit is decoupled from chunk_limit_size. Set whatever you want.
-			queue_limit_length 4096
+		@type memory
+		flush_thread_count 4
+		flush_interval 3s
+		chunk_limit_size 16m      # Logz.io bulk limit is decoupled from chunk_limit_size. Set whatever you want.
+		queue_limit_length 4096
 	</buffer>
 </match>
 
-# # Output every log stream tagged with a 'docker.' prefix to stdout
+# Output every log stream tagged with a 'docker.' prefix to stdout
 # <match docker.*>
 # 	@type stdout
 # </match>

user-simulator/README.md

@@ -1,17 +1,42 @@
-## Commands for running app in container
+## Running app in standalone container
 
-1. Build image from *Dockerfile*
+1. Rename *example.env* to *.env* and supply the `API_SERVER_ADDRESS`. Then run the following commands
 
-		docker build -t eyeezzi/horus-user-simulator .
-		
-2. Start container from image. Note the *public:internal* port mapping
+	> If the API Server is running in another local container with an exposed port, then run this container in the `host` network so it can access the API Server.
 
-		docker run -d eyeezzi/horus-user-simulator
+		docker build --no-cache -t eyeezzi/horus-user-simulator .
+		docker run -d --env-file=.env eyeezzi/horus-user-simulator
+	
+		# if api server is running on localhost:5000
+		docker run -d --env-file=.env --network=host eyeezzi/horus-user-simulator
 
-3. Get the container ID and verify port mapping
+2. Verify that this container is generating logs.
 
-		docker ps
+		docker ps 
+		docker logs -f <container-name>
 
-4. Tail the logs from the container
+## Notes
 
-		docker logs -f <CONTAINER_ID>
+### Useful Commands
+
+- To see all networks on the host
+
+		docker network ls
+
+- To see which network a container is on
+
+		docker inspect <container-name> -f "{{json .NetworkSettings.Networks }}"
+
+- To disconnect a container from a network
+
+		docker network disconnect <network-name> <container-name>
+
+- To connect a container to a network
+
+		docker network connect <network-name> <container-name>
+
+	> Docker seems to have a bug where a container cannot be connected to the `host` network. See this [issue](https://github.com/awslabs/aws-sam-cli/issues/669).
+
+- To list all the containers on a network.
+
+		docker network inspect <network-name> -f "{{json .Containers }}"