go-rest-template

README

💤 go-rest-template

A project template for Go REST API's.

• go-rest-template
  • Features
  • Usage
    • Repository setup
    • Initialize a new project
    • Server
  • Development
    • Start the server
    • Default Routes
    • Adding routes
    • Generate OpenAPI docs
    • Generate Client SDK
• Docker compose
• Kubernetes

Features

• 🔒 Secure by default with automatic TLS powered by CertMagic
• 📈 Prometheus metrics
• 📜 Beautiful logging via charmbracelet
• 📖 OpenAPI documentation built in with SDK generation
• Easy kubernetes development via Tilt
• A full local monitoring stack using Grafana, Prometheus, and Loki via Docker compose.
• 👷 CI pipelines via GitHub actions
  • Tests
  • Linting via golangci-lint
  • Security scanning via gosec
  • Secret scanning via gitleaks
  • Automatic semantic version tagging
  • GoReleaser
  • Docker build and pushes for latest and tagged versions

Usage

Repository setup

The default GitHub actions that come with this project has 1 setup requirement.

1. DOCKERHUB_TOKEN - Login to Docker Hub and create a personal access token with Read, Write scope to push docker images under your account.

[!WARNING] This assumes your Docker Hub namespace matches your git repository namespace. Example: github.com/mynamespace/myrepo will push to mynamespace/myrepo on Docker Hub

1. Enable dependabot updates - Navigate to repository > Security > Code security > Grouped security updates > Enabled

Initialize a new project

Use gonew to initialize a new project from this template:

# Install gonew (if needed)
$ go install golang.org/x/tools/cmd/gonew@latest

# Init project
$ gonew github.com/circa10a/go-rest-template github.com/namespace/project

Finally, replace all of the existing references of the template repository with your newly created one by running:

$ make template

Overview

$ go run .
A template project for Go REST API's

Usage:
  go-rest-template [command]

Available Commands:
  completion  Generate the autocompletion script for the specified shell
  help        Help about any command
  server      Start the go-rest-template server

Flags:
  -h, --help   help for go-rest-template

Use "go-rest-template [command] --help" for more information about a command.

Server

$ go run . server -h

Start the go-rest-template server

Usage:
  go-rest-template server [flags]

Flags:
  -a, --auto-tls                 Enable automatic TLS via Let's Encrypt. Requires port 80/443 open to the internet for domain validation.
  -d, --domains stringArray      Domains to issue certificate for. Must be used with --auto-tls.
  -h, --help                     help for server
  -f, --log-format string        Server logging format. Supported values are 'text' and 'json'. (default "text")
  -l, --log-level string         Server logging level. (default "info")
  -m, --metrics                  Enable Prometheus metrics intrumentation.
  -p, --port int                 Port to listen on. Cannot be used in conjunction with --auto-tls since that will require listening on 80 and 443. (default 8080)
      --tls-certificate string   Path to custom TLS certificate. Cannot be used with --auto-tls.
      --tls-key string           Path to custom TLS key. Cannot be used with --auto-tls.

Development

[!IMPORTANT] Most make targets expect Docker to be installed.

Start the server

$ make run
2024-10-26T19:09:03-07:00 INFO <server/server.go:118> Starting server on :8080 component=server

Default routes

Endpoint	Descripton
localhost:8080/v1/docs	OpenAPI documentation
localhost:8080/v1/health	Health status
localhost:8080/metrics	Prometheus metrics (if server is started with -m)

Adding routes

Routes are created in internal/server/server.go with API handlers in internal/server/handlers/handlers.go.

Generate OpenAPI documentation

Simply add your API spec to api/openapi.yaml then run make docs. The OpenAPI documentation will then be embed in the application and will be accessible at the http://localhost:8080/docs endpoint.

Generate Client SDK

Once your API documention is added to api/openapi.yaml, just run make sdk and a generated client sdk will be output to the api package.

Docker compose

The local docker compose stack sets up a full observability stack for testing. Run the following the start the stack:

$ make docker-compose

The following services will then be accessible with a pre-configured dashboard:

• Go server: http://localhost:8080
• Grafana: http://localhost:3000
• Prometheus: http://localhost:9090
• Loki
• Promtail

Kubernetes

[!NOTE] Requires Tilt to be installed and local kubernetes context to be configured.

This has only been tested on MacOS using Docker for Mac's Kubernetes integration.

$ make k8s

This will deploy the service to kubernetes and make it available at http://localhost:8080