go-template

An opinionated Go project template for scraper, bot, and service workloads. Batteries included: a TLS-fingerprinted HTTP client via fphttp, exponential backoff, bounded concurrency, file-backed state, PostgreSQL, and structured logging.

Quick Start

Install gonew:

go install golang.org/x/tools/cmd/gonew@latest

Scaffold a new project:

gonew github.com/aarock1234/go-template@latest github.com/you/myproject

Clones the template and rewrites all import paths to your module name.

After cloning, run the setup script to configure optional features:

make setup

Setup

Prerequisites: Go 1.26+, Docker, goose, sqlc

1. Replace pkg/template with your own domain logic
2. Update cmd/template/main.go to wire your services
3. Add SQL queries to pkg/db/queries/ and run make generate
4. Copy and configure your environment:

cp .env.example .env

Running

Locally:

make dev

Or with Docker:

make up

Project Structure

go-template/
├── cmd/template/       entrypoint
├── pkg/
│   ├── client/         HTTP client via fphttp (TLS/HTTP2 fingerprinting, proxy, cookies)
│   ├── cycle/          thread-safe round-robin file-backed line cycling
│   ├── db/             PostgreSQL pool, sqlc queries, transactions, advisory locks
│   ├── env/            .env loader and struct-tag validation
│   ├── log/            structured slog with tint and context injection
│   ├── ptr/            generic pointer helpers
│   ├── retry/          exponential backoff with jitter
│   ├── state/          file-backed JSON persistence with file locking
│   ├── template/       skeleton domain service (replace this)
│   └── worker/         bounded-concurrency primitives via errgroup
├── Dockerfile          multi-stage: dev, builder, production (Alpine)
├── compose.yaml        dev mode with docker compose watch
└── Makefile

Development

Command	Description
make dev	Run the application
make build	Compile binary to bin/template
make test	Run tests with race detector via go test -race
make lint	Static analysis via go vet
make fix	Modernize code via go fix
make format	Format code via go fmt
make generate	Run code generation via sqlc generate

Database

Command	Description
make db	Start postgres only (localhost:5432)
make db-down	Stop postgres
make migrate	Run migrations up
make migrate-down	Roll back last migration
make migrate-new	Create a new migration file

The postgres service is opt-in. make db starts it locally on localhost:5432. To use an external database instead, skip make db and set DATABASE_URL in .env to point at your instance.

Docker

Command	Description
make up	Start full stack (app + postgres)
make down	Stop all services
make watch	Hot reload via docker compose watch

Releases

A manual GitHub Actions workflow is provided for releases:

1. Open Actions -> Release
2. Click Run workflow
3. Either:
   • enter an explicit version such as v1.2.3, or
   • leave version empty and choose a patch, minor, or major bump
4. Optionally choose a ref and whether the release is a prerelease

The workflow resolves the final version, validates it, runs go vet and go test -race, pushes the git tag, and creates a GitHub Release with autogenerated notes.

Automatic increment uses the highest existing stable semver tag matching v<major>.<minor>.<patch>. If no tags exist yet, the first auto-incremented release starts from v0.0.1.

Configuration

Configured via environment variables. Copy .env.example to .env to get started.

The HTTP client verifies TLS certificates by default. If you need scraper-style insecure TLS for a specific target, enable it explicitly with client.WithInsecureSkipVerify(true).

Variable	Required	Default	Description
DATABASE_URL	Yes	none	PostgreSQL connection string
LOG_LEVEL	No	info	debug, info, warn, error

License

Elastic License 2.0