Skip to main content
This guide walks you through setting up the Go Template project for local development.

​
Prerequisites

Before you begin, ensure you have the following tools installed:
  • Go 1.26+ - Download Go
  • Docker - Get Docker
  • goose - Database migration tool 
    go install github.com/pressly/goose/v3/cmd/goose@latest
  • sqlc - SQL code generator 
    go install github.com/sqlc-dev/sqlc/cmd/sqlc@latest

​
Initial Setup

1

Clone the project

If you used gonew to scaffold your project, the repository is already cloned:
gonew github.com/aarock1234/go-template@latest github.com/you/myproject
cd myproject
2

Run the setup script

The interactive setup script helps you configure optional features:
make setup
This script will guide you through enabling or disabling features like PostgreSQL support.
3

Configure environment variables

Copy the example environment file and customize it:
cp .env.example .env
Edit .env to configure your settings:
# Log level: debug, info, warn, error
LOG_LEVEL=debug

# Postgres Database URL
DATABASE_URL=postgres://postgres:postgres@localhost:5432/app?sslmode=disable
4

Download dependencies

Install Go module dependencies:
go mod download

​
Available Make Commands

The project includes a Makefile with commonly used development commands:

​
Development Commands

CommandDescription
make devRun the application locally
make buildCompile binary to bin/template
make testRun tests with race detector
make lintStatic analysis via go vet
make fixModernize code via go fix
make formatFormat code via go fmt
make generateRun code generation (sqlc)

​
Quick Examples

make dev

​
Customizing Your Project

After the initial setup, customize the template for your use case:
1

Replace template package

The pkg/template/ directory contains skeleton service code. Replace this with your own domain logic.
2

Update entrypoint

Modify cmd/template/main.go to wire up your services and configure application startup.
3

Add database queries

If using PostgreSQL, add SQL queries to pkg/db/queries/ and run:
make generate
This generates type-safe Go code from your SQL queries using sqlc.

​
Running the Application

Once setup is complete, start the application: 
make dev
This runs the application using go run ./cmd/template, which:
  • Compiles and executes your code
  • Loads environment variables from .env
  • Starts with hot reload during development

​
Next Steps

Docker Setup

Run the full stack with Docker Compose

Database Setup

Configure PostgreSQL and run migrations

Testing

Write and run tests

Build docs developers (and LLMs) love

Get started for freeTalk to us