chi-template

module

v0.0.0-...-04a0fa3 Latest Latest Go to latest Published: Aug 7, 2025 License: MIT

Details

Valid go.mod file
Redistributable license
Tagged version
Stable version
Learn more about best practices

Repository

README ¶

A modern, production-ready Go REST API template with full observability, Docker Compose orchestration, and best practices for configuration, documentation, and testing.

Features

Go 1.24 with idiomatic project structure
Chi router for fast, composable HTTP routing
PostgreSQL with SQLC for type-safe queries
Redis for caching
OpenTelemetry for distributed tracing and metrics
Prometheus, Grafana, Loki, Tempo, cAdvisor, Node Exporter for full observability (metrics, logs, traces)
Swagger (Swaggo) for API documentation
Viper for configuration management
GoMock for service and repository testing
Docker Compose for local development and orchestration
Provisioned Grafana dashboards and datasources
GoDoc and Swagger comments for all public APIs and endpoints

Structure

cmd/ — Application entrypoint
internal/ — Main application code (handlers, services, repositories, models, middleware, etc)
deploy/ — Docker Compose, Grafana, Prometheus, Loki, Tempo, and other infra configs
docs/ — Swagger/OpenAPI docs

Getting Started

Clone the repository:
```
git clone <repo-url>
cd chi-template
```
Copy and edit the .env file:
```
cp .env.example .env
# Edit as needed
```
Install the dependencies:
```
make setup
```
Build and run with Docker Compose:
```
make compose_up
```

Development

Run tests:
```
make test
```
Generate Swagger docs:
```
make docgen
```
Hot reload (optional): Use Air for live reload during development.

What’s Included

CRUD endpoints for movies (with SQLC and repository/service pattern)
Full observability stack (metrics, logs, traces) wired to Grafana
Example Grafana dashboards for Docker, host, and application metrics
API documentation with Swaggo/Swagger
GoDoc comments for all packages and public functions
Example GoMock usage for service and repository tests
Docker Compose for all services and infrastructure

How to Extend

Add new endpoints in internal/handler/ and internal/service/
Add new SQLC queries in internal/db/queries/ and regenerate with sqlc generate
Add new Grafana dashboards in deploy/grafana/provisioning/dashboards/
Add new Prometheus scrape configs in deploy/prometheus/prometheus.yml

Directories ¶

?	: This menu
/	: Search site
f or F	: Jump to
y or Y	: Canonical URL

Path	Synopsis
cmd
docs Package docs Code generated by swaggo/swag.	Package docs Code generated by swaggo/swag.
internal
configs Handles loading and validation of environment variables	Handles loading and validation of environment variables
db Package db handles database connection establishment and session management.	Package db handles database connection establishment and session management.
db/repository Package repository is a generated GoMock package.	Package repository is a generated GoMock package.
db/sqlc
handler Package handler provides HTTP handlers for movie-related endpoints.	Package handler provides HTTP handlers for movie-related endpoints.
helpers Package helpers provides utility functions for logging and HTTP JSON responses.	Package helpers provides utility functions for logging and HTTP JSON responses.
middleware Package middleware contains custom middlewares for the application.	Package middleware contains custom middlewares for the application.
models Package models defines the application's data structures and domain models.	Package models defines the application's data structures and domain models.
o11y Package o11y provides observability (tracing, metrics, logging) setup for the application.	Package o11y provides observability (tracing, metrics, logging) setup for the application.
redis Package redis handles Redis client connection establishment and session management.	Package redis handles Redis client connection establishment and session management.
server Package server provides the HTTP server setup and lifecycle management.	Package server provides the HTTP server setup and lifecycle management.
service Package service is a generated GoMock package.	Package service is a generated GoMock package.
types Package types defines shared types and response structures for the application.	Package types defines shared types and response structures for the application.
validation Package validation provides functions and types for input validation and business rule enforcement.	Package validation provides functions and types for input validation and business rule enforcement.