Skip to main content

​
Prerequisites

Before you begin, make sure you have:
The template uses generics and features from Go 1.26. Earlier versions are not supported.

​
Installation

1

Install gonew

gonew is a Go tool that clones templates and automatically rewrites import paths to your module name.
go install golang.org/x/tools/cmd/gonew@latest
Verify the installation:
gonew --help
2

Scaffold your project

Replace github.com/you/myproject with your actual module path:
gonew github.com/aarock1234/go-template@latest github.com/you/myproject
This command:
  • Clones the template repository
  • Rewrites all import paths from github.com/aarock1234/go-template to github.com/you/myproject
  • Creates a new directory named myproject
Make sure the module path matches your actual GitHub username or organization.
3

Navigate to your project

cd myproject
4

Run the setup wizard

The setup wizard lets you choose which features to keep and which to remove:
make setup
You’ll be prompted to configure:
  • Docker support (Dockerfile + compose)
  • PostgreSQL support (database + migrations)
  • Optional packages (HTTP client, worker pool, retry, etc.)
All features are pre-selected by default. Just press Enter to keep everything, or deselect what you don’t need.
5

Configure environment

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

# PostgreSQL connection (if you kept database support)
DATABASE_URL=postgres://postgres:postgres@localhost:5432/app?sslmode=disable
6

Run your application

make dev
This runs the application directly on your machine.

​
What You Get

After running the setup wizard, your project will have: 
myproject/
├── cmd/template/main.go    # Application entrypoint
├── pkg/
│   ├── template/           # Example service (replace with your logic)
│   ├── env/                # Config loader
│   ├── log/                # Structured logging
│   └── ...                 # Optional packages you selected
├── .env                    # Your environment configuration
├── Makefile                # Development commands
└── go.mod                  # Go module with your import path

​
Example Output

The template includes a working example that demonstrates the HTTP client: 
$ make dev
go run ./cmd/template
2026-03-04T10:30:45.123Z INFO template application started
2026-03-04T10:30:45.456Z INFO example response response=...
The example service in pkg/template/example.go makes a request to a TLS fingerprinting test endpoint: 
func (t *Template) Example(ctx context.Context) (*Response, error) {
    req, err := http.NewRequestWithContext(ctx, http.MethodGet,
        "https://tls.peet.ws/api/all", nil)
    if err != nil {
        return nil, fmt.Errorf("creating request: %w", err)
    }

    resp, err := t.http.Do(req)
    if err != nil {
        return nil, fmt.Errorf("executing request: %w", err)
    }
    defer resp.Body.Close()

    return parseResponse(resp)
}

​
Next Steps

Now that you have a working project:

Setup Guide

Learn more about the setup wizard and customization options

Development

Explore available make commands and development workflow

​
Common Commands

Here are the most frequently used commands:
CommandDescription
make devRun the application locally
make buildCompile binary to bin/template
make testRun tests with race detector
make lintStatic analysis with go vet
make formatFormat code with go fmt
Run make help to see all available commands.

​
Troubleshooting

Make sure $GOPATH/bin is in your PATH. Add this to your shell profile:
export PATH="$PATH:$(go env GOPATH)/bin"
Then reload your shell or run source ~/.bashrc (or ~/.zshrc).
If you’re using the Docker postgres:
make db
If using an external database, verify your DATABASE_URL in .env is correct.
Run go mod tidy to clean up module dependencies:
go mod tidy
The setup wizard runs this automatically, but you may need it if you add new imports.

Build docs developers (and LLMs) love

Get started for freeTalk to us