go-boilerplate

README

A minimal Go boilerplate. Comes with JWT auth, PostgreSQL, and a clean architecture.

---

Tech Stack

Backend

Language	Go
Router	Chi
Database	PostgreSQL via pgx
Migrations	Goose
Auth	JWT (access + refresh tokens) + bcrypt
Config	Koanf + godotenv
Logging	Zerolog
Validation	go-playground/validator
Live Reload	Air
Task Runner	Task

Prerequisites

• Go 1.25+
• PostgreSQL
• Task

---

Getting Started

1. Clone the repository

git clone https://github.com/joyyth/go-boilerplate.git my-app
cd my-app

2. Database Setup

Ensure you have a PostgreSQL database running.

CREATE DATABASE yourapp;

3. Backend Setup

cd backend

# copy and configure environment variables
cp .env.sample .env

# start with live reload — migrations run automatically on startup
task dev

---

Using This Boilerplate

When starting a new project:

1. Rename the module — find and replace github.com/joyyth/go-boilerplate with your module path in go.mod and all imports
2. Rename the env prefix — find and replace YOURAPP_ with your app name (e.g. MYSHOP_) across all files
3. Update ServiceName in cmd/main.go
4. Add your domain — follow the existing user pattern: model → repository → service → handler → register in routes.go and container.go

---

Backend Tasks

task dev                  # run with live reload
task run                  # run without live reload
task build                # build binary to ./bin/backend
task test                 # run all tests
task tidy                 # format and tidy dependencies

task migrations:install   # install goose CLI
task migrations:new       # create a new migration  (name=migration_name)
task migrations:up        # apply all pending migrations  (DB_DSN=...)
task migrations:status    # show migration status  (DB_DSN=...)