Introduction

A production-ready Go backend boilerplate with clean architecture, PostgreSQL, Redis, and background job processing

Welcome to Boiler-Go

Boiler-Go is a production-ready Go backend boilerplate that provides a solid foundation for building scalable web services. It combines clean architecture principles with battle-tested libraries and production-ready patterns.

Quick start

Get your backend running in under 5 minutes

Architecture

Understand the project structure and design patterns

API endpoints

Explore the available HTTP endpoints

Configuration

Learn how to configure your application

Key features

Boiler-Go comes packed with production-ready features out of the box:

Thread-safe database pool

Concurrent-safe PostgreSQL connection management with pgx/v5

Background jobs

Redis-based task processing with Asynq for reliable job execution

Graceful shutdown

Proper resource cleanup and timeout handling for both API and worker

Structured logging

JSON logging with request tracing and correlation IDs using zerolog

Health checks

Lightweight service health monitoring with duration tracking

Worker management

API endpoints for worker status and ping testing

Tech stack

Boiler-Go is built on modern, production-tested libraries:

Core backend

• Echo v4 - High performance HTTP router and middleware framework
• pgx/v5 - Fast PostgreSQL driver and toolkit
• sqlc - Type-safe SQL code generation

Background jobs and caching

• Asynq - Redis-based distributed task queue
• go-redis/v9 - Type-safe Redis client

Configuration and logging

• env/v11 - Environment variable parsing with validation
• zerolog - Zero-allocation JSON logger

Production ready

Boiler-Go includes several production-ready features that are often overlooked in boilerplates:

Thread safety

• Database pool uses sync.RWMutex for concurrent access
• Configuration loading uses sync.Once for safe singleton pattern
• All shared resources are properly synchronized

Observability

• Structured JSON logging throughout the application
• Request correlation via X-Request-ID header
• Request IDs propagated from API to worker logs
• Global fallback logger for non-request contexts

Error handling

• Comprehensive error checking and logging
• Graceful degradation on service failures
• Proper resource cleanup on errors
• Context-aware timeouts

Resource management

• Connection pooling with configurable limits
• Context-aware database initialization with timeouts
• Automatic cleanup on shutdown
• Memory leak prevention

What you’ll build

With Boiler-Go, you get a complete backend system:

1. HTTP API server - Handles incoming requests with structured logging and middleware
2. Background worker - Processes asynchronous tasks from Redis queues
3. Health monitoring - Exposes health check endpoints for load balancers
4. Worker management - Test and monitor your background job processing

Both the API server and worker process share the same codebase and configuration, making deployment and maintenance straightforward.

Next steps

1. Get started

   Follow the quickstart guide to set up your development environment and run your first API server

2. Understand the architecture

   Learn about the project structure and design patterns used throughout the codebase

3. Explore the API

   Check out the API reference to see what endpoints are available

4. Customize

   Adapt the boilerplate to your needs by adding new handlers, tasks, and business logic