gloss

gloss (Golang open simple service) provides boilerplate routing, database setup, and Docker files to get a minimal microservice up and running. It includes example code to increment and retrieve counter values from a PostgreSQL database. Ideally, one would fork, or clone + mirror push this repository, then edit the handlers + routes, database queries, and configurations for their own purposes. It uses chi for routing, and pgx for its PostgreSQL database driver, but other databases or routers can be used by implementing the Database interface from domain.go, and/or the Handler interface from net/http.

Prerequisites

• Docker
• Golang (for a non-Docker build)

Running

Using Docker

If you have Docker installed, getting the example stack up and running is as simple as:

./bootstrap_example.sh

This will build the image locally with a gloss:latest tag, then deploy a service stack with a PostgreSQL instance exposed on port 5432, and the example gloss service exposed on port 8080 on the host machine.

Local build

If you don't want to use Docker stack, you can build and run the example service locally.

You must first have a PostgreSQL service exposed on your host machine at port 5432, with the configuration in test.env, for example (using Docker cli for brevity):

docker run -d -p 5432:5432 \
-e POSTGRES_PASSWORD="password" \
-e POSTGRES_USER="test" \
-e POSTGRES_DB="test" \
postgres

then you can build and run the service locally:

# get the dependencies
go get -d ./...

# install to ~/go/bin
go install ./...

# export the test environment variables
while read l; do export $l; done < test.env

# run the service (this binds to port 8080 and waits for requests)
~/go/bin/gloss

Interacting with the example counter service

If you have deployed the example successfully, you can interact with the service at http://localhost:8080/v1

Example interaction:

# @URL: http://localhost:8080/v1/counter/{counterId}
# - POST: to increment/create a counter in the database
# - GET: to get the current counter value, if it exists

# create a counter with ID 4
curl -v http://localhost:8080/v1/counter/4 -X POST

# a counter has now been created with ID 4 and value 0

# increment it a few times
for i in $(seq 1 10); do curl -v http://localhost:8080/v1/counter/4 -X POST; done

# get the counter value
curl -v http://localhost:8080/v1/counter/4
# returns 10

# connect to the database and run some other queries
psql -h localhost -p 5432 -U test -d test

Adapting to your own implementation

Database

• Add your business logic methods to the Database interface (found in domain.go), then implement them in a custom package
  • See the IncrementCounter and GetCounterVal methods for an example of this, implemented in the pgsql package
  • You can also just edit the pgsql package and change the domain interface methods if you want to continue using PostgreSQL

Routing

• Implement the net/http Handler interface, or edit the existing implementation in the chi package
  • Replace/change the example handler bodies in handlers.go to perform your business logic
  • Update the routes in handlers.go:setupRoutes to use your handlers

Putting it all together

• Pass an instance of your Database implementation to your custom Handler, and use the instance to perform business logic in handler functions
  • An example of this is shown in cmd/gloss/main.go, where pgsql's Database implementation is used with chi's Handler implementation
  • A pgsql.Database instance is created, then passed as a parameter to chi.NewRouter, which creates a router, associates handler functions in the chi package with routes, then stores the pgsql.Database instance so it can be used in the custom handlers

Disclaimer and considerations for deployment

The deployment scripts, configurations, and any defaults included in this repository are not, under any circumstances, to be used in production. They are here to provide a basic example deployment so you can quickly get up and running in a development environment. For a legitimate deployment, you must first edit them, or create your own configurations with secure settings.

As stated above, the responsibility to properly secure your code and deployment is entirely yours, but here are some things you may want to consider:

• Ensure timeouts and size defaults are configured properly for the http.Server in cmd/gloss/main.go
• Use SSL for communication with the database
• Choose routing middleware to fit your needs
• Properly manage credentials used/shared by the microservice and database

License

This project is licensed under the terms of the MIT license.