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
    ├── cert/                        # Certificates & Keys
    ├── config/                      # Configuration logic
    │   └── ...
    ├── 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
    |   │   └── ...                  # Other rest api handlers
    │   ├── middleware/              # Middleware for HTTP requests
    │   ├── db/
    │   │   ├── migrations/          # Migrations files for goose
    │   │   ├── queries/             # Raw Queries for SQLC to ingest
    │   │   ├── sqlc/                # Autogenerated Factory of queries
    │   │   ├── db.go                # Database connection setup
    │   │   └── ...                  # Other db logic
    │   ├── httpx/                   # req/res global handler
    │   │   ├── problem_details.go   # RFC 9457 error report
    │   │   ├── request.go           # Request parsing and validation
    │   │   ├── response.go          # Response serialization
    │   │   └── validation.go        # Validation logic setup and error report
    │   ├── jwt/                     # Jwt authentication setup
    │   ├── server/
    │   │   ├── print.go             # Prints existing routes
    │   │   ├── routes.go            # route registration and mounting
    │   │   └── server.go            # Server Setup
    │   └── utils/                   # Common utility functions
    ├── .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 targeted towards supported os & architecture . 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

Deployment

k3s.yml file is used for deployment to kubernetes.

• use commands for make-jwt in deployment k3s environment to generate the certificates
• add secret with base64 encoded

      apiVersion: v1
  kind: Secret
  metadata:
  name: jwt-keys
  namespace: <namespace>
  type: Opaque
  data:
  jwt-pvt.pem: LS0tLS1CRUdJTiBFQyBQ...   # Replace with actual base64-encoded content
  jwt-pub.pem: LS0tLS1CRUdJTiBQVUJMSUMgS0VZ...   # Replace with actual base64-encoded content

• generating base64 string on unix systems

  base64 -w 0 jwt-pvt.pem
  base64 -w 0 jwt-pub.pem

• do the same with cloudflare origin certificates and use them to serve tls traffic