Golang Api Starter

This is a monolithic http api starter with sane defaults. Features include:

• air - hot-reloading dev server
• slog - global logging
• chi/v5 - routing & middleware
• pgx/v5 - database connectivity with smart pooling
• sqlc - type safe queries, utilising pgx driver
• goose - database migrations without adding to app dependency
• bcrypt - password hashing
• golang-jwt/jwt/v5 - jwt Authentication
• validator/v10 - incoming request payload validation
• envconfig - app configuration parsing & validation
• prometheus/promhttp for default metrics
• Makefile commands for toolchain

Folder Structure

The project follows below folder structure:

project-root/
    ├── cmd/
    │   ├── api                      # Server entrypoint
    │   │   └── main.go              # Server entrypoint
    │   └── routes                   # Server route printer
    │       └── main.go              # Server route printer
    ├── cert/                        # Certificates & Keys
    ├── config/                      # Configuration logic
    │   ├── config.go
    │   └── ...
    ├── docs/                        # Project documentations
    │   ├── bruno/                   # Bruno collection for exploring api
    │   │   └── ...
    ├── internal/                    # Encapsulted Applicaton Logic
    |   ├── api/                     # API-related code (e.g. REST)
    |   │   ├── auth/
    │   │   │   ├── handler.go       # Http handler, validation & serialization
    │   │   │   ├── service.go       # Business logic aka. service
    │   │   │   ├── repository.go    # Encapsulated database interactions
    │   │   │   ├── router.go        # Http routes specific to auth
    │   │   │   └── schema.go        # Necessary schemas for validation
    │   ├── middleware/              # Middleware for HTTP requests
    │   │   └── ...
    │   ├── db/
    │   │   ├── migrations/          # Migrations files for goose
    │   │   ├── query/               # Raw Queries for SQLC to ingest
    │   │   ├── sqlc/                # Autogenerated Factory of queries
    │   │   ├── db.go                # Database connection setup
    │   │   └── ...                  # Other application logic
    │   ├── server/
    │   │   ├── routes.go            # Migrations files for goose
    │   │   └──  server.go           # Server Setup
    │   └── utils/                   # reusable packages
    │       └── <name>/
    │           └── ...              # Public package code
    ├── .gitignore                   # Gitignore file
    ├── Makefile                     # Runnable Scripts
    ├── go.mod                       # Go module file
    ├── go.sum                       # Go module dependencies file
    └── README.md                    # Project README

Building Binaries

use below command to build binaries targetted towards supported os & architechture . A github workflow file is also included

make build os=<OPERATING SYSTEM> arch=<ARCHITECHTURE>

Get Started - Development

Environment

Ensure following tools available in your machine

• Docker >= v27
• Docker Compose >=v2.29
• OpenSSL >= 1.1.1

Server

To run the development server use below command:

make init

This command will

• Copy .env.example to .env, filling in default values
• Generate TLS cert for serving https locally.
• Generate ECDSA public-private key pair for JWT Auth locally.
• Start development server in hot reload mode
• Migrate database to latest migration

After running above command for the first time, you should only start development server in hot reload mode using below command

make dev

n.b. In production environment, mount your certificates in cert directory, ensure proper name & path supplied in env.

Exploring APIs

Bruno is an Opensource IDE For Exploring and Testing Api's, lightweight alternative to postman/insomnia. Open Directory docs/bruno from the bruno app & the collection will show up. Choose the environment Local.

Download & install bruno -> click here.

Other Commands

install & clean golang dependencies

make tidy
make deps

run the development server with hot reload

make dev

run migration of postgresql database, ensure .env values are correctly given

make migrate-up

revert migrations by 1 level

make migrate-down

create migration files

make migrate-create f=<filename>

Generate TLS cert for serving https locally.

make tls

Generate ECDSA public-private key pair for JWT Auth locally.

make jwt

Run linter

make lint