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.
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.
go install github.com/Educentr/go-project-starter/cmd/go-project-starter@latest1. 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 wizard for new projects
go-project-starter init --target=./myservice
# Preview changes before generating
go-project-starter --dry-run --config=config.yaml3. Start developing:
cd myservice
make docker-up # Start dependencies (Postgres, Redis, etc.)
make generate # Generate code from OpenAPI specs
make run # Start your serviceAccess your service:
- REST API:
http://localhost:8080 - System endpoints:
http://localhost:9090(health, metrics, pprof)
| 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.
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!
}- REST APIs (OpenAPI 3.0 via ogen)
- gRPC Services (Protocol Buffers v3)
- Kafka Consumers (event-driven architecture)
- Background Workers (Telegram bots, daemons)
One codebase, multiple deployment profiles:
applications:
- name: gateway
transport: [rest_api, grpc_users]
- name: workers
workers: [telegram_bot, kafka_consumer]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)
3-level configuration priority with runtime updates:
- Default — hardcoded in application
- Transport-level —
/{service}/transport/rest/{transportName}/{key} - 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 OnlineConfGenerate ready-to-use integration test infrastructure:
main:
goat_tests: trueThis provides:
TestEnvInitializerfor database and service setupBaseTestSuitewith common test utilities- Mock servers for external API dependencies
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)
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.
📖 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 |
pip install mkdocs-material mkdocs-mermaid2-plugin
mkdocs serveThen open http://localhost:8000
This project is licensed under the MIT License - see the LICENSE.txt file for details.
Built with these amazing open-source projects:
- ogen - OpenAPI 3.0 code generation
- go-activerecord - Database ORM and migrations
- zerolog - Structured logging
- logrus - Structured logging
- Prometheus - Monitoring and metrics
- Traefik - Reverse proxy and load balancer
- Documentation - Complete guides and API references
- GitHub Discussions - Ask questions, share ideas
- Issue Tracker - Report bugs, request features
Stop writing boilerplate. Start building features.
go install github.com/Educentr/go-project-starter/cmd/go-project-starter@latest