Go HTTP server

A simple Go HTTP server boilerplate with Echo, structured logging, and Docker support. Includes graceful shutdown on SIGINT/SIGTERM via errgroup.

Project layout

cmd/app/                     entrypoint, wiring, graceful shutdown
cmd/app/handler/             HTTP handlers and route registration
internal/config/             env-based configuration
internal/domain/             your business logic goes here
internal/infrastructure/os/  signal handling
pkg/logger/                  Zap logger setup

Endpoints

Method	Path	Description
GET	/health	Liveness check (200 OK)

Adding an endpoint

Register routes in a setup…Routes method and call it from handler.New (see cmd/app/handler/health.go):

func (h *Handler) setupFooRoutes(e *echo.Echo) {
    e.GET("/foo", h.getFoo)
}

Prerequisites

• Go 1.25+
• Docker and Docker Compose (for containerized runs)

Configuration

Copy the example environment file and adjust values if needed:

cp .env.dist .env

The application reads configuration from process environment variables (via envconfig). Docker Compose loads .env automatically. For a local go run, export variables or source the file:

set -a && source .env && set +a

Variable	Default	Description
LOG_LEVEL	info	Zap log level (debug, info, warn, error)
API_PORT	3000	HTTP listen port
API_READ_TIMEOUT	7	Server read timeout (seconds)
API_WRITE_TIMEOUT	5	Server write timeout (seconds)
API_IDLE_TIMEOUT	5	Server idle timeout (seconds)
API_TIMEOUT	5	Reserved for future use

Inside Docker, the process always listens on port 3000; API_PORT in .env controls the host port mapping.

Run with Docker (recommended)

make setup-docker   # copy .env, download modules, build and start containers

Or step by step:

make setup-local    # copy .env (if missing) and go mod download
make run            # docker compose up --build

Verify:

curl http://localhost:3000/health

Stop:

make down

Run locally (without Docker)

make setup-local
make run-local

Build binary

make build
./bin/server

Make targets

make help

Common targets: run, run-local, down, setup-local, setup-docker, build, tests, lint.