Go API app Template

An opinionated DIY template for Golang JSON API applications

What's in the box?

App

• Router (chi)
• Real IP middleware (chi)
• Request ID middleware
• Error recovery middleware
• CORS middleware (chi)
• Compatibility with standard library (net/http) middleware
• Error handling
• Secure Configurable Authentication (based on Refresh Tokens)
• Transactional Emails via Scaleway
• CAPTCHA via Cloudflare Turnstile

Database

• ORM (bun)
• Language-agnostic database migration toolkit (dbmate)

Background jobs processing

• Background jobs processing setup via Asynq

Quality control

• Testing setup (ginkgo)
• Github Actions Test job
• Github Actions Lint job (golangci-lint)

Misc

• Structured logger (slog)
• Configuration (viper)

Development and deployment

• Docker Compose setup for development
• Multi-stage Dockerfile
• Hot-reload via Air

Prerequisites

• Install Go
• Install Docker

Running the app locally

1. Install developer tools

./setup-dev.sh

2. Install packages

go mod download

3. Start database and Redis servers

docker compose up postgres redis

4. Run database migrations

The second part of the command is a workaround until dbmate image supports postgres version 18

docker compose run --rm dbmate migrate && docker compose run --rm dump_schema

5. Seed the database

docker compose run --rm psql --echo-all --file /db/seed.sql

6. Start the app

air -c ./.air.server.toml

# Or (without hot reload)
go run -tags=debug cmd/server/main.go

Recreating the database

# Drop the database
docker compose run --rm dbmate drop

# Create the database and run migrations
docker compose run --rm dbmate up

Running the background jobs processor locally

1. Set up the database

Make sure that steps 1-4 from Running the app locally are completed

2. Start the worker

air -c ./.air.worker.toml

# Or (without hot reload)
go run -tags=debug cmd/worker/main.go

Running the background jobs scheduler (CRON-like) locally

1. Set up the database

Make sure that steps 1-4 from Running the app locally are completed

2. Start the scheduler

air -c ./.air.scheduler.toml

# Or (without hot reload)
go run -tags=debug cmd/scheduler/main.go

Running tests

docker compose run --build --rm test

Running the linter

docker compose run --build --rm lint

Building the production image

Server, worker and scheduler binaries will be in the same image

docker build . --tag go-api-template:latest

Enabling linters in IDE

https://golangci-lint.run/docs/welcome/integrations/