go-api-boilerplate

Go API Boilerplate

A slightly opinionated HTTP API boilerplate with the Go programming language, following (some) Clean Architecture principles.

Features

• HTTP server with net/http;
• Testing suites, assertions and mocks with testify;
• Live reload with air;
• Logging with zerolog;
• Configuration with viper;
• PostgreSQL database connection with pgx and sqlx
• Pre-configured CI job with Github Actions;
• JWT authentication (under the with-auth branch)

Requirements

• Go 1.24 (or newer)
• GNU Make
• Docker
• air: live-reloading
• migrate: database migrations

First run

1. Create .env file

cp .env.example .env

1. Rename packages to your project's name

make rename-pkgs

1. Run setup script

make setup

Running locally

To start a local server with live-reload and all necessary containers, execute:

make run

Testing

To execute all test suites and get a coverage report at the end, just run:

make test

Building for production

With Docker

There's a Dockerfile.prod included with the project to build an optimized image based on distroless, so you just need to adapt it for your needs and publish to your desired registry.

# This should be set by your CI/CD system
export BUILD_ID="$(uuidgen)"

# Building the image
docker build . \
  -t mathcale/go-api-boilerplate \
  -f Dockerfile.prod \
  --build-arg BUILD_ID

# Clean intermediate images
docker image prune \
  --filter label=stage=builder \
  --filter label=build=$BUILD_ID

Manually

By running the following command, the application will be compiled and outputted to the bin directory.

make build

Next Steps

• Add database connection
• Add logging middleware
• Add Github Actions CI workflow
• Add database
• Add authentication branch
• Add OpenAPI specs on web handlers
• Improve project structure documentation