app-service

README

# A boilerplate HTTP-REST server to be built upon

:toc:
:toc-placement: preamble
:sectnums:
:experimental:

image:https://quay.io/repository/redhat-developer/app-service/status["Docker Repository on Quay", link="https://quay.io/repository/redhat-developer/app-service"]
image:https://circleci.com/gh/redhat-developer/app-service/tree/master.svg?style=svg["Build Status", link="https://circleci.com/gh/redhat-developer/app-service/tree/master"]
image:https://goreportcard.com/badge/github.com/redhat-developer/app-service[Go Report Card, link="https://goreportcard.com/report/github.com/redhat-developer/app-service"]
image:https://godoc.org/github.com/redhat-developer/app-service?status.png[GoDoc,link="https://godoc.org/github.com/redhat-developer/app-service"]
image:https://codecov.io/gh/redhat-developer/app-service/branch/master/graph/badge.svg[Codecov.io,link="https://codecov.io/gh/redhat-developer/app-service"]


This project provides the code to build a HTTP-REST server with some good defaults and features already configured. Among those are:

 * a `/status?format=yaml` and `/status?format=json` endpoint for health-checking the server
 * graceful shutdown of HTTP server
 * Apache combined logging output
 * porwerful configuration with defaults
 * support for golden files to capture HTTP requests and responses
 * an easy to use Makefile
 * ready-to-use docker containerization

= To build and run the server...

All scenarios below require you to clone an navigate to your code:

[source,bash]
----
# Clone the project
git clone https://github.com/redhat-developer/app-service ${GOPATH}/src/github.com/redhat-developer/app-service

# Navigate to the project
cd ${GOPATH}/src/github.com/redhat-developer/app-service
----

== Scenario: Using docker

These instructions show you all the things you need to build and run the server on your local machine.

[source,bash]
----
# Build and run the image 
make VERBOSE=1 docker-run
----

In another terminal run this  command to query the `/status/yaml` endpoint:

[source,bash]
----
curl -v 0.0.0.0:8001/status?format=yaml
----

== Scenario: Using native tools

These instructions show you all the things you need to build and run the server on your local machine.

[source,bash]
----
# Build the server
make VERBOSE=1 all

# Run tests including coverage analysis
make VERBOSE=1 test-coverage

# Run the server and configure an HTTP address to listen on
APP_HTTP_ADDRESS=0.0.0.0:8088 ./out/app-server
----

In another terminal run this  command to query the `/status/yaml` endpoint:

[source,bash]
----
curl -v 0.0.0.0:8001/status?format=yaml
----

= Make targets

Here's a list of `make` targets and their purpose.

**Notice:** On each invocation of `make` we check that we can find these tools: `go`, `dep`, and `git`. The list of required tools only differs when you run `docker-image` or `docker-run`. Then we will only search for `docker`, since everything else is done inside a container and you don't need to have the aforementioned tools available on your local machine.

make all:: Builds the app server and places it in `./out/app-server`. This is the default target if no target is specified.

make test:: Runs all tests in all packages without any coverage information. Upon the first error, we don't continue running any other tests.

make test-coverage:: Runs all tests and collects coverage information that will be stored in `./out/cover.out`.

make test-coverage-html:: Opens a browser to show you the annotated source code with coverage information from `./out/cover.out`. If `./out/cover.out` doesn't exist yet it will be generated by running the tests with coverage analysis.

make clean:: Removes all build and tests artifacts from `./out` and removes the `./vendor` directory.

make docker-image:: Creates a docker image called `redhat-developer/app-service:${GIT_COMMIT_ID}-dirty`. There's no need to change the name of the `redhat-developer/app-service` to something else. If you've checked out the project in `${GOPATH}/src/github.com/myorg/myrepo`, then your image will  automatically be called `myorg/myrepo:${GIT_COMMIT_ID}-dirty`. Notice, that the `-dirty` extension is only there if you've untracked changes in your local directory.

make docker-run:: This target depends on `make docker-image` so it runs it before doing anything else. Then it runs the created image in the foreground and publishes the service's default port 8080 to the host. This is probably the easiest way to run try out the application server without the need to have all the tools available that are required to build the project. Once the service is up you can run `curl 0.0.0.0:8001/status?format=yaml` to check that it works.