gin-boilerplate-examples

README

Go Boilerplate

An API boilerplate written in Golang with Gin Framework and Gorm

Motivation

Write restful API with fast development and developer friendly

Table of Contents

• Motivation
• Configuration Manage
  • ENV Manage
  • Server Configuration
  • Database Configuration
  • PgAdmin
• Installation
  • Local Setup Instruction
  • Develop Application in Docker with Live Reload
• Middlewares
• Boilerplate Structure
• Code Examples
• Let's Build an API
• Deployment
  • Container Development Build
  • Container Production Build and Up
• Useful Commands
• ENV YAML Configure
• Use Packages

Configuration Manage

ENV Manage

• Default ENV Configuration Manage from .env. sample file .env.example

# Server Configuration
SECRET=h9wt*pasj6796j##w(w8=xaje8tpi6h*r&hzgrz065u&ed+k2)
DEBUG=True # `False` in Production
ALLOWED_HOSTS=0.0.0.0
SERVER_HOST=0.0.0.0
SERVER_PORT=8000

# Database Configuration
MASTER_DB_NAME=test_pg_go
MASTER_DB_USER=mamun
MASTER_DB_PASSWORD=123
MASTER_DB_HOST=postgres_db
MASTER_DB_PORT=5432
MASTER_DB_LOG_MODE=True # `False` in Production
MASTER_SSL_MODE=disable

REPLICA_DB_NAME=test_pg_go
REPLICA_DB_USER=mamun
REPLICA_DB_PASSWORD=123
REPLICA_DB_HOST=localhost
REPLICA_DB_PORT=5432
REPLICA_DB_LOG_MODE=True # `False` in Production
REPLICA_SSL_MODE=disable

• Server DEBUG set False in Production
• Database Logger MASTER_DB_LOG_MODE and REPLICA_DB_LOG_MODE set False in production
• If ENV Manage from YAML file add a config.yml file and configuration db.go and server.go. See More ENV YAML Configure

Server Configuration

• Use Gin Web Framework

Database Configuration

• Use GORM as an ORM
• Use database MASTER_DB_HOST value set as localhost for local development, and use postgres_db for docker development

PG Admin

• Check PG Admin on http://0.0.0.0:5050/browser/
• Login with Credential Email admin@admin.com Password root
• Connect Database Host as postgres_db, DB Username and Password as per .env set
• Note: if not configure .env, default Username mamun and password 123

Installation

Local Setup Instruction

Follow these steps:

• Copy .env.example as .env and configure necessary values
• To add all dependencies for a package in your module go get . in the current directory
• Locally run go run main.go or go build main.go and run ./main
• Check Application health available on 0.0.0.0:8000/health

Develop Application in Docker with Live Reload

Follow these steps:

• Make sure install the latest version of docker and docker-compose
• Docker Installation for your desire OS https://docs.docker.com/engine/install/ubuntu/
• Docker Composer Installation https://docs.docker.com/compose/install/
• Run and Develop make dev
• Check Application health available on 0.0.0.0:8000/health

Middlewares

• Use Gin CORSMiddleware

router := gin.New()
router.Use(gin.Logger())
router.Use(gin.Recovery())
router.Use(middleware.CORSMiddleware())

Boilerplate Structure

├── controllers
│   └── base_controller.go
├── docker-compose-dev.yml
├── docker-compose-prod.yml
├── Dockerfile
├── Dockerfile-dev
├── go.mod
├── go.sum
├── LICENSE
├── main.go
├── Makefile
├── models
│   └── example_model.go
├── pkg
│   ├── config
│   │   ├── config.go
│   │   ├── db.go
│   │   └── server.go
│   ├── database
│   │   ├── database.go
│   │   └── migration.go
│   ├── helpers
│   │   ├── pagination
│   │   │   └── pagination.go
│   │   ├── response.go
│   │   └── search.go
│   └── logger
│       └── logger.go
├── README.md
├── repository
│   └── example_repo.go
└── routers
    ├── index.go
    ├── middleware
    │   └── cors.go
    └── router.go

Examples

• More Example gin-boilerplate-examples

Let's Build an API

1. models folder add a new file name example_model.go

package models

import (
	"time"
)

type Example struct {
	Id        int        `json:"id"`
	Data      string     `json:"data" binding:"required"`
	CreatedAt *time.Time `json:"created_at,string,omitempty"`
	UpdatedAt *time.Time `json:"updated_at_at,string,omitempty"`
}
// TableName is Database Table Name of this model
func (e *Example) TableName() string {
	return "examples"
}

1. Add Model to migration

package database

import (
	"gin-boilerplate/models"
)
//Add list of model add for migrations
var migrationModels = []interface{}{&models.Example{}}

1. controller folder add a file example_controller.go

• Create API Endpoint
• Use any syntax of GORM after base.DB, this is wrapper of *gorm.DB

package controllers

import (
	"gin-boilerplate/models"
	"gin-boilerplate/pkg/logger"
	"github.com/gin-gonic/gin"
	"net/http"
)

func (base *Controller) CreateExample(ctx *gin.Context) {
	example := new(models.Example)

	err := ctx.ShouldBindJSON(&example)
	if err != nil {
		logger.Errorf("error: %v", err)
		ctx.JSON(http.StatusBadRequest, gin.H{"error": err.Error()})
		return
	}
	err = base.DB.Create(&example).Error
	if err != nil {
		logger.Errorf("error: %v", err)
		ctx.JSON(http.StatusBadRequest, gin.H{"error": err.Error()})
		return
	}
	ctx.JSON(http.StatusOK, &example)
}

1. routers folder add a file example.go

package routers

import (
	"github.com/gin-gonic/gin"
	"gorm.io/gorm"
	"gin-boilerplate/controllers"
)


func TestRoutes(route *gin.Engine, db *gorm.DB) {
	ctrl := controllers.Controller{DB: db}
	v1 := route.Group("/v1")
	v1.POST("/example/", ctrl.CreateExample)
}

1. Finally, register routes to index.go

package routers

import (
	"github.com/gin-gonic/gin"
	"gorm.io/gorm"
	"net/http"
)

//RegisterRoutes add all routing list here automatically get main router
func RegisterRoutes(route *gin.Engine, db *gorm.DB) {
	//Add All route
	TestRoutes(route, db)
}

• Congratulation, your new endpoint 0.0.0.0:8000/v1/example/

Deployment

Container Development Build

• Run make build

Container Production Build and Up

• Run make production

ENV Yaml Configure

database:
  driver: "postgres"
  dbname: "test_pg_go"
  username: "mamun"
  password: "123"
  host: "postgres_db" # use `localhost` for local development
  port: "5432"
  ssl_mode: disable
  log_mode: false

server:
  host: "0.0.0.0"
  port: "8000"
  secret: "secret"
  allow_hosts: "localhost"
  debug: false #use `false` in production
  request:
    timeout: 100

• Server Config

func ServerConfig() string {
viper.SetDefault("server.host", "0.0.0.0")
viper.SetDefault("server.port", "8000")
appServer := fmt.Sprintf("%s:%s", viper.GetString("server.host"), viper.GetString("server.port"))
return appServer
}

• DB Config

func DbConfiguration() string {
	
dbname := viper.GetString("database.dbname")
username := viper.GetString("database.username")
password := viper.GetString("database.password")
host := viper.GetString("database.host")
port := viper.GetString("database.port")
sslMode := viper.GetString("database.ssl_mode")

dsn := fmt.Sprintf("host=%s user=%s password=%s dbname=%s port=%s sslmode=%s",
host, username, password, dbname, port, sslMode)
return dsn
}

Useful Commands

• make dev: make dev for development work
• make build: make build container
• make production: docker production build and up
• clean: clean for all clear docker images

Use Packages

• Viper - Go configuration with fangs.
• Gorm - The fantastic ORM library for Golang
• Logger - Structured, pluggable logging for Go.
• Air - Live reload for Go apps (Docker Development)