Golang Template

A production-ready Go backend template with PostgreSQL, Redis, and observability built-in.

Features

• Go 1.25 - Latest Go version with modern patterns
• PostgreSQL - Database with pgx/v5 connection pool
• Redis - Caching and session storage
• New Relic - Application performance monitoring and distributed tracing
• Structured Logging - zerolog with JSON output in production
• Configuration Management - koanf with environment variable support
• Database Migrations - tern for version-controlled migrations
• Code Quality - golangci-lint with strict linting rules
• Task Automation - Taskfile for common development tasks

Prerequisites

• Go 1.25+
• Task - For running development tasks
• PostgreSQL - Database
• Redis - Cache/Session store

Quick Start

1. Clone and Setup

# Clone the repository
git clone <your-repo-url>
cd golang-template

# Install Go dependencies
cd backend && go mod download && cd ..

2. Environment Configuration

Copy the example environment file and configure your settings:

# Create your environment file
cp backend/.env.example backend/.env

Configure the following required environment variables:

# Required Configuration
TEMPLATE_ENV=local
TEMPLATE_SERVER_PORT=8080
TEMPLATE_SERVER_READ_TIMEOUT=30
TEMPLATE_SERVER_WRITE_TIMEOUT=30
TEMPLATE_SERVER_IDLE_TIMEOUT=120
TEMPLATE_SERVER_CORS_ALLOWED_ORIGINS=http://localhost:3000,http://localhost:8080

# Database Configuration
TEMPLATE_DATABASE_HOST=localhost
TEMPLATE_DATABASE_PORT=5432
TEMPLATE_DATABASE_USER=postgres
TEMPLATE_DATABASE_PASSWORD=your_password
TEMPLATE_DATABASE_NAME=golang_template
TEMPLATE_DATABASE_SSL_MODE=disable
TEMPLATE_DATABASE_MAX_OPEN_CONNS=25
TEMPLATE_DATABASE_MAX_IDLE_CONNSS=25
TEMPLATE_DATABASE_CONN_MAX_LIFETIME=300
TEMPLATE_DATABASE_CONN_MAX_IDLE_TIME=60

# Auth Configuration
TEMPLATE_AUTH_SECRET_KEY=your-secret-key-min-32-chars

# Redis Configuration
TEMPLATE_REDIS_ADDRESS=localhost:6379

# Observability (Optional)
TEMPLATE_OBSERVABILITY_LOGGING_LEVEL=debug
TEMPLATE_OBSERVABILITY_LOGGING_FORMAT=console
TEMPLATE_OBSERVABILITY_NEWRELIC_LICENSE_KEY=
TEMPLATE_OBSERVABILITY_NEWRELIC_APP_LOG_FORWARDING_ENABLED=false
TEMPLATE_OBSERVABILITY_NEWRELIC_DISTRIBUTED_TRACING_ENABLED=false

3. Database Setup

# Create your database
createdb golang_template

# Run migrations (requires TASKFILE_DB_DSN environment variable)
export TEMPLATE_DB_DSN="postgres://postgres:password@localhost:5432/golang_template?sslmode=disable"
task migrations:up

4. Run the Application

# From the backend directory
cd backend
go run ./cmd/golang-template

Or use the task runner:

task run

Development Tasks

This project uses Taskfile for common development tasks:

# Show all available tasks
task help

# Run the application
task run

# Create a new migration
task migrations:new name=create_users_table

# Apply all pending migrations
task migrations:up

# Format code and tidy dependencies
task tidy

Code Quality

Linting

# Run linter
cd backend && golangci-lint run ./...

# Or use the config from root if configured

Formatting

# Format Go code
cd backend && go fmt ./...

# Format with goimports
cd backend && goimports -w .

Project Structure

golang-template/
├── backend/
│   ├── cmd/
│   │   └── golang-template/     # Application entrypoint
│   │       └── main.go
│   ├── internal/
│   │   ├── config/             # Configuration management
│   │   ├── database/           # Database connection and migrations
│   │   │   └── migrations/     # SQL migration files
│   │   ├── errs/               # Custom error types
│   │   ├── handler/            # HTTP handlers
│   │   ├── lib/                # Utility libraries
│   │   ├── logger/             # Logging setup
│   │   ├── middleware/         # HTTP middleware
│   │   ├── model/              # Data models
│   │   ├── repository/         # Data access layer
│   │   ├── router/             # HTTP routing
│   │   ├── server/             # HTTP server setup
│   │   ├── service/            # Business logic
│   │   ├── sqlerr/             # SQL error handling
│   │   ├── testing/            # Test utilities
│   │   └── validation/         # Input validation
│   ├── static/                 # Static assets
│   ├── .env                    # Environment variables (not committed)
│   ├── .env.example            # Example environment file
│   ├── go.mod                  # Go module dependencies
│   ├── go.sum                  # Dependency checksums
│   ├── golangci.yaml           # Linter configuration
│   └── Taskfile.yml            # Development tasks
├── packages/                   # Shared packages (monorepo)
├── package.json                # Node.js configuration (for turbo)
├── turbo.json                  # Turborepo configuration
├── bun.lock                    # Bun lockfile
└── README.md                   # This file

Key Technologies

Category	Technology	Purpose
Language	Go 1.25	Backend application
Database	PostgreSQL + pgx/v5	Primary data store
Cache	Redis	Session/caching
Observability	New Relic	APM & tracing
Logging	zerolog	Structured logging
Config	koanf	Environment-based config
Migrations	tern	Database migrations
Linting	golangci-lint	Code quality

Configuration Details

Environment Variable Prefix

All environment variables are prefixed with TEMPLATE_ to avoid conflicts. The prefix is stripped when loaded into the configuration struct.

Configuration Validation

All required configuration values are validated at startup. The application will not start if any required configuration is missing or invalid.

Observability

The application supports New Relic for application performance monitoring. To enable:

1. Obtain a license key from New Relic
2. Set TEMPLATE_OBSERVABILITY_NEWRELIC_LICENSE_KEY
3. Optionally enable log forwarding and distributed tracing

License

MIT