Go Gin Starter

If you’ve built more than one Go API, you already know the truth: the “hard part” isn’t writing handlers it’s rebuilding the same scaffolding every time (config, routing, DB wiring, migrations, local tooling, Docker, folder conventions), then keeping it clean as the codebase grows.

Go Gin Starter is a starter template for building backend services with Golang + Gin, intentionally organized around Clean Architecture principles and a pragmatic developer workflow: run locally with hot reload (Air), or run containerized via Docker Compose.

Overview

• What it is: A Go + Gin backend boilerplate structured as a template repository.
• Who it’s for: Engineers building REST-style APIs who want consistent layering and predictable setup.
• Primary value: Faster project spin-up with a clean baseline for maintainability and scaling.

At a glance

• Go version target: Go 1.23
• Database: PostgreSQL
• Core libraries: Gin, pgx, Viper, golang-migrate, zerolog, Air

Background

As projects grow, the cost of inconsistent structure shows up as slower onboarding, tangled dependencies, and brittle changes. Clean Architecture is often used to impose boundaries so business logic doesn’t get trapped inside transport or persistence code.

This template exists to give you those boundaries from day one, without forcing you to reinvent the same foundational setup on every project.

The Problem

Most “hello world” API templates don’t hold up once you introduce real requirements:

• You need separation between HTTP delivery, use cases, and data access.
• You need reproducible local runs (hot reload, env handling) and reproducible deployments (Docker).
• You need a clear convention for where things live so the next engineer doesn’t reverse-engineer your intentions.

Without a baseline, each new service becomes a one-off which becomes expensive quickly.

The Solution

Go Gin Starter provides a consistent structure and toolchain:

• A layered project layout (Clean Architecture oriented) to prevent dependency sprawl.
• PostgreSQL + pgx as the default DB path (fast, production-friendly).
• Viper-based config and an .env.example to standardize environment setup.
• Air hot reload for fast iteration in local development.
• Dockerfile + Docker Compose workflow for reproducible runs.

Core

• Gin-based HTTP server foundation
• PostgreSQL integration via pgx
• Config management via Viper
• DB migration support via golang-migrate
• Structured logging via zerolog
• Local hot reload via Air
• Docker containerization support

Architecture

Responsibility boundaries (intended)

• Delivery layer: request parsing, validation, HTTP concerns
• Use case layer: business rules, orchestration
• Repository layer: persistence and external IO
• Infra/config: DB connection, env/config, logging, migrations

Tech Stack

• Backend: Go (1.23), Gin
• Data: PostgreSQL, pgx
• Config: Viper
• Migrations: golang-migrate
• Logging: zerolog
• Dev workflow: Air (hot reload), Makefile
• Containerization: Dockerfile + Docker Compose

Getting Started

Prerequisites

• Go installed (targeting Go 1.23)
• Docker + Docker Compose (optional but recommended)
• PostgreSQL (if running outside Docker)

Installation

1. Clone the repository:

   git clone https://github.com/JordanMarcelino/go-gin-starter
   cd go-gin-starter
   

2. Copy env config:

   cp .env.example .env
   

Run (Local with hot reload)

air

Run (Docker)

docker compose up -d --build

Usage

This template is intended as a starting point for building APIs. Typical workflow:

1. Define your domain model and use cases (business logic).
2. Implement repositories for persistence (PostgreSQL).
3. Expose use cases through Gin routes/handlers.
4. Add migrations for schema evolution.
5. Run locally with air, then validate containerized runs with Docker Compose.