A boilerplate HTTP-REST server to be built upon

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

• a /status/yaml and /status/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:

# Clone the project
git clone https://github.com/kwk/boilerplate-app ${GOPATH}/src/github.com/kwk/boilerplate-app

# Navigate to the project
cd ${GOPATH}/src/github.com/kwk/boilerplate-app

1. Scenario: Using docker

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

# Build and run the image
make VERBOSE=1 docker-run

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

curl -v 0.0.0.0:8001/status?format=yaml

2. Scenario: Using native tools

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

# Build the server
make VERBOSE=1 all

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

# Run the server and confiugre 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:

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 kwk/boilerplate-app:${GIT_COMMIT_ID}-dirty. There’s no need to change the name of the kwk/boilerplate-app 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.