Getting started
This page walks from an empty machine to a running HTTP API with a migrated database. It also calls out common pitfalls (wrong .env, database not reachable, port already in use).
Prerequisites
| Tool | Minimum | Notes |
|---|---|---|
| Go | 1.23+ | Match go directive in go.mod; install from go.dev. |
| PostgreSQL | 14+ recommended | Local install or Docker; SQLite is only for certain test helpers. |
| Git | any | To clone the template. |
| Make | optional | Convenience targets; you can always use go run cmd/main.go .... |
On macOS, brew install go postgresql is often enough for local development.
1. Clone the repository
git clone https://github.com/Caknoooo/go-gin-clean-starter.git
cd go-gin-clean-starter
If you are working inside a monorepo, copy the tree instead of cloning — just keep module path in go.mod consistent with your import prefix.
2. Install Go modules
go mod download
If corporate proxies block public modules, configure GOPROXY and GOSUMDB according to your organisation policy.
3. Configure environment variables
cp .env.example .env
Open .env and set at least:
| Variable | Example | Purpose |
|---|---|---|
DB_HOST | localhost | PostgreSQL host |
DB_PORT | 5432 | Port |
DB_USER | postgres | Username |
DB_PASS | secret | Password |
DB_NAME | gin_starter | Database name — create this database empty before migrating |
JWT_SECRET | long random string | Never use the template default in production |
GOLANG_PORT | 8888 | HTTP listen port |
APP_ENV | localhost | When set to localhost, the server binds 0.0.0.0 so phones on the same Wi‑Fi can hit your laptop |
Email (optional for first run)
If you skip SMTP configuration, flows that send mail (verification / reset) may log or error depending on your config/email.go setup. That is fine for learning JWT login first; wire SMTP when you need real messages.
4. Create the database
Using psql:
createdb gin_starter
# or
psql -c "CREATE DATABASE gin_starter;"
Using Docker only for Postgres:
docker run --name pg -e POSTGRES_PASSWORD=secret -e POSTGRES_DB=gin_starter -p 5432:5432 -d postgres:16
Ensure DB_* in .env matches the container.
5. Run migrations
From the project root:
go run cmd/main.go --migrate:run
You should see log output indicating applied migrations. Verify with:
go run cmd/main.go --migrate:status
If this fails, typical causes are:
- Wrong password or database does not exist.
- Extension issues on managed Postgres — the starter may run
uuid-ossp; adjust privileges on cloud providers if needed.
6. (Optional) Seed sample data
go run cmd/main.go --seed
Inspect database/seeders to see what gets inserted. Seeds are idempotent only if written that way — read the seeder code before relying on it in shared environments.
7. Start the HTTP server
go run cmd/main.go --run
Without --run, the process exits after handling CLI flags only. The Makefile target make run usually wraps the correct invocation — check the file for the exact command.
Smoke tests
| Request | Expected |
|---|---|
GET http://localhost:8888/api/user | Paginated JSON (may be empty after fresh migrate) |
POST /api/auth/register | Creates a user when body matches validation rules |
POST /api/auth/login | Returns access_token and refresh_token |
Use curl, HTTPie, or Bruno/Postman collections you maintain.
8. Run automated tests
go test ./...
Some tests may spin up SQLite or use test databases — read config.SetUpTestDatabaseConnection and test packages if failures mention DSN or drivers.
9. Optional: Docker Compose stack
If the repository ships docker-compose.yml, it typically wires nginx, app, and postgres for a closer‑to‑prod layout. For day‑one learning, plain go run against local Postgres is simpler.
Next steps
- Read Architecture to understand
config.Init→providers.NewApp→RegisterModule. - Read Database & migrations before you change schema — keep entities and migrations aligned.
When something fails, capture the first error line from the terminal and the migration status output; that narrows problems quickly.