Skip to content

About

Fast and easy start you go project

Resources

Contributing

Stars

3 stars

Watchers

1 watching

Forks

Repository files navigation

Go Project Starter

Transform your API specifications into production-ready microservices in minutes, not days.

A powerful, opinionated microservice scaffolding tool that generates complete, production-grade Go services from YAML configuration files. Built for developers who need to rapidly build business services with REST APIs, gRPC, background workers, and event-driven architectures—without sacrificing code quality or flexibility.

Go Version License: MIT GitHub Stars Code Generation Templates


Why Go Project Starter?

Building a production-ready microservice from scratch typically takes 2-3 weeks of repetitive boilerplate work. Go Project Starter reduces this to 5 minutes by generating 100% of your infrastructure code from a single YAML configuration file.

The game-changer? Unlike traditional scaffolding tools that generate code once and leave you on your own, Go Project Starter uses intelligent disclaimer markers to separate generated code from your custom business logic. This means you can regenerate your entire project as your API evolves without losing your manual changes.


Quick Start

Installation

go install github.com/Educentr/go-project-starter/cmd/go-project-starter@latest

Generate Your First Service

1. Create a configuration file (config.yaml):

main:
  name: myservice
  logger: zerolog
  use_active_record: true

git:
  repo: github.com/myorg/myservice
  module_path: github.com/myorg/myservice

rest:
  - name: api
    path: [./api/openapi.yaml]
    generator_type: ogen
    port: 8080
    version: v1

  - name: system
    generator_type: template
    generator_template: sys
    port: 9090
    version: v1

applications:
  - name: server
    transport: [api, system]

2. Run the generator:

go-project-starter --config=config.yaml

Interactive Project Setup (Alternative)

# Interactive wizard for new projects
go-project-starter init --target=./myservice

# Preview changes before generating
go-project-starter --dry-run --config=config.yaml

3. Start developing:

cd myservice
make docker-up    # Start dependencies (Postgres, Redis, etc.)
make generate     # Generate code from OpenAPI specs
make run          # Start your service

Access your service:

  • REST API: http://localhost:8080
  • System endpoints: http://localhost:9090 (health, metrics, pprof)

CLI Commands

Command Description
go-project-starter --config=... Generate project from YAML config
go-project-starter init Interactive wizard for new projects
go-project-starter setup Configure CI/CD, servers, deploy scripts
go-project-starter migrate Migrate config to new generator version

Use --dry-run to preview changes without writing files.


Key Features

Intelligent Code Preservation

Regenerate your entire project structure as your APIs evolve—add new endpoints, modify data models, update dependencies—without losing a single line of your custom business logic.

// ==========================================
// GENERATED CODE - DO NOT EDIT ABOVE THIS LINE
// ==========================================

func (h *Handler) CreateUser(ctx context.Context, req *CreateUserRequest) (*User, error) {
    // Your custom business logic here - survives regeneration!
}

Multi-Protocol Support

  • REST APIs (OpenAPI 3.0 via ogen)
  • gRPC Services (Protocol Buffers v3)
  • Kafka Consumers (event-driven architecture)
  • Background Workers (Telegram bots, daemons)

Application-Based Scaling

One codebase, multiple deployment profiles:

applications:
  - name: gateway
    transport: [rest_api, grpc_users]

  - name: workers
    workers: [telegram_bot, kafka_consumer]

Production-Ready Infrastructure

Every generated project includes:

  • Docker & Docker Compose (multi-stage builds, ~50MB images)
  • GitHub Actions CI/CD
  • Traefik reverse proxy
  • Prometheus metrics & Grafana dashboards
  • Health checks & graceful shutdown
  • Structured logging (zerolog or logrus)

Dynamic Configuration (OnlineConf)

3-level configuration priority with runtime updates:

  1. Default — hardcoded in application
  2. Transport-level — /{service}/transport/rest/{transportName}/{key}
  3. App-specific — /{service}/transport/rest/{transportName}/{appName}/{key}

Enable local dev environment with OnlineConf Admin UI:

main:
  dev_stand: true  # Generates docker-compose-dev.yaml with OnlineConf

Integration Testing (GOAT)

Generate ready-to-use integration test infrastructure:

main:
  goat_tests: true

This provides:

  • TestEnvInitializer for database and service setup
  • BaseTestSuite with common test utilities
  • Mock servers for external API dependencies

What You Get

myservice/                    # ~50 files, ~8,000 lines of production-ready code
├── cmd/server/              # Application entry point with graceful shutdown
├── internal/
│   ├── app/                 # Transport handlers & workers (your code goes here)
│   └── pkg/                 # Business logic & repositories
├── pkg/                     # Runtime libraries (middleware, logging, metrics)
├── docker-compose.yaml      # Production environment
├── docker-compose-dev.yaml  # Local dev with OnlineConf (dev_stand: true)
├── Dockerfile               # Multi-stage build (50MB final image)
├── Makefile                 # 40+ targets (see docs/reference/makefile-targets.md)
└── .github/workflows/       # CI/CD (test, build, push to registry)

Architecture

Generated projects follow a clean three-layer design:

Layer Purpose Config Dependency
pkg/ Runtime libraries, reusable across projects No
internal/pkg/ Business logic, repositories (returns errors) No
internal/app/ Transport handlers, workers (logs errors) Yes

Dependencies flow only downward. This separation enables testing without configuration and clear responsibility boundaries.


Documentation

📖 Full Documentation — Complete guides, API references, and examples.

Section Description
Getting Started Installation and first project
Architecture Generator and generated project design
Configuration Complete YAML configuration guide
CLI Commands and options
Workflow Regeneration, Makefile, OnlineConf
Examples Ready-to-use configurations
Testing GOAT integration tests
Reference Naming conventions, Makefile targets, YAML schema
Troubleshooting FAQ and common issues
Comparison vs Goa, go-zero, Sponge, grpc-gateway
Contributing How to contribute

Local Documentation

pip install mkdocs-material mkdocs-mermaid2-plugin
mkdocs serve

Then open http://localhost:8000


License

This project is licensed under the MIT License - see the LICENSE.txt file for details.


Acknowledgments

Built with these amazing open-source projects:


Getting Help & Support


Stop writing boilerplate. Start building features.

go install github.com/Educentr/go-project-starter/cmd/go-project-starter@latest

Get Started • View Examples • Read Docs

About

Fast and easy start you go project

Resources

Contributing

Stars

3 stars

Watchers

1 watching

Forks

Releases

Packages

Contributors

Languages