fix: rename binary to aerogear-app-metrics & update docs (#24)

* fix: rename default binary name to aerogear-app-metrics

* feat(docs): Major updates to README.md

* fix: minor issues in README.md

.gitignore

@@ -1,5 +1,6 @@
 vendor/
 .idea/
-metrics
+aerogear-app-metrics
 dist/
-coverage*.out
+coverage*.out
+.DS_Store

.goreleaser.yml

@@ -2,7 +2,7 @@
 # Build customization
 builds:
   # makefile currently relies on this name
-  - binary: metrics
+  - binary: aerogear-app-metrics
     main: ./cmd/metrics-api/metrics-api.go
     goos:
       - windows

Dockerfile

@@ -1,6 +1,6 @@
 FROM centos:7.4.1708
-ARG BINARY=./metrics
+ARG BINARY=./aerogear-app-metrics
 EXPOSE 3000
 
-COPY ${BINARY} /opt/metrics
-ENTRYPOINT ["/opt/metrics"]
+COPY ${BINARY} /opt/aerogear-app-metrics
+ENTRYPOINT ["/opt/aerogear-app-metrics"]

README.md

@@ -1,110 +1,147 @@
-# AeroGear App Metrics
+# Aerogear App Metrics
 
-This is the server component of the AeroGear Metrics Service. It is a RESTful API that allows mobile clients to send metrics data which will get stored in a PostgreSQL database. The service is written in [Golang](https://golang.org/).
+This is the server component of the Aerogear Metrics Service. It is a RESTful API that allows mobile clients to send metrics data which will get stored in a PostgreSQL database. The service is written in [Golang](https://golang.org/).
 
 ## Prerequisites
 
 * [Install Golang](https://golang.org/doc/install)
+* [Ensure the $GOPATH environment variable is set](https://github.com/golang/go/wiki/SettingGOPATH)
 * [Install the dep package manager](https://golang.github.io/dep/docs/installation.html)
 * [Install Docker and Docker Compose](https://docs.docker.com/compose/install/)
 
 See the [Contributing Guide](./CONTRIBUTING.md) for more information.
 
 
-## Local development setup and building
+## Getting Started
 
-This section documents how to setup a local development environment, if you only wish to run the project with minimal setup, check the [Containerized building and running](#containerized-building-and-running) section.
+This section documents the ideal setup for local development. If you'd like to simply run the entire application in `docker-compose`, check out the relevant section.
 
-In Go, projects are typically kept in a [workspace](https://golang.org/doc/code.html#Workspaces) that follows a very specific architecture. Before cloning this repo, be sure you have a `GOPATH` env var that points to your workspace folder, say:
+Golang projects are kept in a [workspace](https://golang.org/doc/code.html#Workspaces) that follows a very specific architecture. Before cloning this repo, be sure you have a `$GOPATH` environment variable set up.
 
-```sh
-$ echo $GOPATH
-/Users/JohnDoe/workspaces/go
-```
-
-Then clone this repository by running:
+### Clone the Repsitory
 
 ```
 git clone [email protected]:aerogear/aerogear-app-metrics.git $GOPATH/src/github.com/aerogear/aerogear-app-metrics
 ```
 
-And finally install dependencies:
+### Install Dependencies
 ```
 make setup
 ```
 
-It is also possible to build the binaries by simply running:
+Note this is using the `dep` package manager under the hood. You will see the dependencies installed in the `vendor` folder.
+
+### Start the Database
+
 ```
-make build
+docker-compose up db
 ```
 
-## Running the project
+### Start the Server
 
-### Containerized building and running
-
-You can use [Docker Compose](https://docs.docker.com/compose/) to run the project without requiring any extra setup other than a working docker installation.
+```
+go run cmd/metrics-api/metrics-api.go
 
+2018/02/27 10:51:54 Starting application... going to listen on :3000
 ```
-docker-compose up
+
+The application's default configuration will allow it to connect to the database created by `docker-compose`.
+
+You can test out the healthcheck endpoint:
+
 ```
+curl -i http://localhost:3000/healthz
 
-This will run both the `db` and `api` services. If you wish to run only the database use `docker-compose up db`.
+HTTP/1.1 200 OK
+Content-Type: application/json; charset=UTF-8
+Date: Tue, 27 Feb 2018 10:53:16 GMT
+Content-Length: 56
 
-The setup targets local development and testing, as such it utilizes the host's TCP ports 3000 for the API service and postgres' default port 5432.
+{"time":"2018-02-27T10:53:16.313301415Z","status":"ok"}
+```
 
-This means that these ports could be in use if you have another postgres instance running or other test web servers.
+### Run Entire Application with Docker Compose
 
-### Running from source
+This section shows how to start the entire application with `docker-compose`. This is useful for doing some quick tests (using the SDKs) for example.
 
-Utilize the `go run` command to transparently compile and run the project:
+First, compile a Linux compatible binary:
 
 ```
-go run cmd/metrics-api/metrics-api.go
+make build_linux
 ```
 
-You can verify the server is running by GET-ing its health check endpoint:
+This binary will be used to build the Docker image. Now start the entire application.
+
 ```
-curl http://localhost:3000/healthz
+docker-compose up
 ```
 
-The default configuration will allow the application to connect to the PostgreSQL container.
+### Example Client Request
 
-### Running a locally-built binary in a container
+This section shows an example `curl` request which can be used to send some data to the `/metrics` endpoint.
 
-In order to run a locally-built binary in a container utilize the main `Dockerfile` via :
+```
+curl -i -X POST \
+  http://localhost:3000/metrics \
+  -H 'Cache-Control: no-cache' \
+  -H 'Content-Type: application/json' \
+  -H 'Postman-Token: 87bf2b99-7cdc-8df9-9b2d-6cdcd2932159' \
+  -d '{
+  "clientId": "453de7432",
+  "data": {
+    "app": {
+      "id": "com.example.someApp",
+      "sdkVersion": "2.4.6",
+      "appVersion": "256"
+    },
+    "device": {
+      "platform": "android",
+      "platformVersion": "27"
+    }
+  }
+}'
+```
+
+You will see the returned back in the response. 
+
+If you have the `psql` command line tools you can connect to the Database and verify the data was inserted.
 
 ```
-make docker_build
+psql -U postgresql -d aerogear_mobile_metrics --host localhost
+Password for user postgresql: # postgres
+
+aerogear_mobile_metrics=> select * from mobileappmetrics;
 ```
 
-This will copy a binary from the default output location for `make build_linux` command, and build an image from it.
+## Builds and Testing
 
-## Release
+The `makefile` provided provides commands for building and testing the code. For now, only the most important commands are documented.
 
-Build and publish to github releases using `goreleaser`, see `.goreleaser.yml` for configuration.
+* `make setup` - Downloads the application dependencies.
 
-First make sure you have this tool installed: [Intalling Goreleaser](https://goreleaser.com/#introduction.installing_goreleaser).
+* `make build` - Compiles a binary for your current system. The binary is output at `./aerogear-app-metrics`.
 
-Then tag your release, replacing `x` with the appropriate version:
-```
-git tag -a v0.0.x -m "Release 0.0.x"
-```
+* `make build_linux` - Compiles a Linux compatible binary. The binary is output at `./dist/linux_amd64/aerogear-app-metrics`. This is mainly used for Docker builds. `make build` can still be used if you are a Linux user.
 
-And make the release:
-```
-make release
-```
+* `make docker_build` - Builds a Binary from source and uses that binary to create a Docker image.
 
-### Releasing a built container
+* `make test` - Runs the unit tests (alias for `make test-unit`).
 
-This repository also contains a set of commands to push the built container images to the `aerogear` docker hub organization.
+* `make test-integration` - Runs unit tests and integration tests. This requires a running database server.
 
-These commands should preferrably run in a CD server, but are documented here for completeness and when required to be run locally
+* `make test-integration-cover` - Same as `make test-integration` but also generates a code coverage report. Used in the CI service.
 
-```
-# Add your dockerhub credentials to the environment variables
-DOCKERHUB_USERNAME={} DOCKERHUB_PASSWORD={} make docker_push_master
 
-# Manually add the tag information that would otherwise come from CI server metadata
-RELEASE_TAG=v0.0.1 make docker_push_release
-```
+## How to Release a New Version
+
+The release process for Aerogear maintainers is very simple. From the Github UI, simply create a release. **The release tag and title must be in the format `x.y.z`**. Formats such as `1.0` or `v1.0.0` are not valid.
+
+This will kick off an automated process in the CI service, where the following steps occur:
+
+* The release tag is checked out.
+* The code is built and the full test suite is run.
+* The [goreleaser](https://goreleaser.com/) tool generates a Changelog and binaries for Windows, MacOS and Linux. These are added to the release created in Github.
+* A new docker image is built and given the tags `latest` and `<git tag>` (where `<git tag>` is the `x.y.z` tag that was used).
+* The docker image is pushed to the Aerogear organization in Github.
+
+The automated release process takes 2-3 minutes to complete on average.

docker-compose.yml

@@ -13,7 +13,7 @@ services:
     build:
       context: .
       args:
-        BINARY: ./dist/linux_amd64/metrics
+        BINARY: ./dist/linux_amd64/aerogear-app-metrics
     environment:
       PGHOST: db
       PGUSER: postgresql

makefile

@@ -5,10 +5,10 @@ PACKAGES     ?= $(shell sh -c "find $(TOP_SRC_DIRS) -name \\*_test.go \
                    -exec dirname {} \\; | sort | uniq")
 BIN_DIR := $(GOPATH)/bin
 SHELL = /bin/bash
-BINARY ?= metrics
+BINARY ?= aerogear-app-metrics
 
 # This follows the output format for goreleaser
-BINARY_LINUX_64 = ./dist/linux_amd64/metrics
+BINARY_LINUX_64 = ./dist/linux_amd64/aerogear-app-metrics
 
 DOCKER_LATEST_TAG = aerogear/$(APP_NAME):latest
 DOCKER_MASTER_TAG = aerogear/$(APP_NAME):master
@@ -41,6 +41,9 @@ docker_build_release:
 docker_build_master:
 	docker build -t $(DOCKER_MASTER_TAG) --build-arg BINARY=$(BINARY_LINUX_64) .
 
+.PHONY: test
+test: test-unit
+
 .PHONY: test-unit
 test-unit:
 	@echo Running tests: