Vibecoder Heaven - Golang App

Ready to go template for creating Go services in one repository. It includes example of:

• RESTful API
• Background worker

Quickstart

In both cases infra runs in docker containers. After running open http://localhost:8080/spec/ to browse API specification.

Run app locally

cp .env.example .env
make start-infra
make start

Run app in docker

cp .env.example .env
docker compose build
docker compose up

Development

1. Edit spec/openapi.yaml
2. Run make generate
3. Update server implementation

Adding new service

1. Create new main file in cmd, for example cmd/worker/main.go. Place startup code here
2. Place business logic in internal/app/worker
3. Reuse internal/model and internal/storage. Services uses shared domain model and storage layer.

Testing

Running Tests

# Set test database URI (required for storage tests)
export TEST_POSTGRES_URI="postgres://postgres:postgres@localhost:5432/postgres?sslmode=disable"

# Run all tests
make test

# Run only short/unit tests (no database required)
make test-short

# Run integration tests
make test-integration

Database Tests

Storage layer tests use gitlab.gx-testdmnweb.com/go-libs/pg/pgtest which automatically:

• Sets up an isolated test database for each test
• Runs migrations from the migrations package
• Cleans up after tests complete

Tests are marked with t.Parallel() and run concurrently with isolated databases.

Requirements:

• PostgreSQL must be running (use make start-infra)
• TEST_POSTGRES_URI environment variable must be set (see .env.example)

Conventions

Go generate

Add tools to go generate as described above.

Use pattern *.gen.go for generated files.

Go tools

Tools should be installed with versioning and use go.mod tool section.

Use tools with

go tool <name> <args>

Adding tools

go get -tool github.com/golangci/golangci-lint/v2/cmd/golangci-lint@v2.6.1
go get -tool github.com/air-verse/air@v1.63.0

Removing tools

Add @none as version to remove tool

go get -tool honnef.co/go/tools/cmd/staticcheck@none