gomicrogen

A powerful CLI tool to scaffold Go microservice projects with a predefined folder structure and production-ready templates.

🚀 Features

Quick Project Scaffolding: Generate complete Go microservice projects in seconds
Production-Ready Templates: Includes Docker, Kubernetes, database migrations, and more
Customizable Configuration: Flexible flags for database, Redis, ports, and environment settings
Git Integration: Automatic Git repository initialization with dev branch
Go Module Management: Automatic go mod init and go mod tidy execution
Comprehensive Structure: Well-organized folder structure following Go best practices
Hot Reload Support: Includes Air configuration for development
API Documentation: Swagger/OpenAPI integration
Observability: OpenTelemetry and Uptrace integration
Database Migrations: Built-in migration support with golang-migrate

📋 Prerequisites

Go 1.23.0 or higher
Git (for repository initialization)
Docker (optional, for containerization)

🛠️ Installation

Quick Install (Recommended)

Linux/macOS

# One-liner installation (recommended)
curl -fsSL https://raw.githubusercontent.com/surahj/gomicrogen/main/install-oneline.sh | bash

# Or download and run the full installer
curl -fsSL https://raw.githubusercontent.com/surahj/gomicrogen/main/install.sh | bash

Windows (PowerShell)

# Run the PowerShell installer
Invoke-Expression (Invoke-WebRequest -Uri "https://raw.githubusercontent.com/surahj/gomicrogen/main/install.ps1" -UseBasicParsing).Content

Manual Installation

Download the appropriate binary for your platform from the latest release:

Linux

# Download and extract the package
wget https://github.com/surahj/gomicrogen/releases/latest/download/gomicrogen-linux-amd64.tar.gz
tar -xzf gomicrogen-linux-amd64.tar.gz

# Install binary and templates
sudo cp gomicrogen-linux-amd64-package/gomicrogen-linux-amd64 /usr/local/bin/gomicrogen
sudo chmod +x /usr/local/bin/gomicrogen
sudo mkdir -p /usr/local/bin/templates
sudo cp -r gomicrogen-linux-amd64-package/templates/* /usr/local/bin/templates/

macOS

# Download and extract the package
curl -L https://github.com/surahj/gomicrogen/releases/latest/download/gomicrogen-darwin-amd64.tar.gz | tar -xz

# Install binary and templates
sudo cp gomicrogen-darwin-amd64-package/gomicrogen-darwin-amd64 /usr/local/bin/gomicrogen
sudo chmod +x /usr/local/bin/gomicrogen
sudo mkdir -p /usr/local/bin/templates
sudo cp -r gomicrogen-darwin-amd64-package/templates/* /usr/local/bin/templates/

Windows

# Download and extract from the latest release
# Then add the extracted directory to your PATH

From Source

# Clone the repository
git clone https://github.com/surahj/gomicrogen.git
cd gomicrogen

# Build the binary
go build -o gomicrogen

# Make it executable
chmod +x gomicrogen

# Move to a directory in your PATH (optional)
sudo mv gomicrogen /usr/local/bin/

Using Go Install

go install github.com/surahj/gomicrogen@latest

Using Docker

# Pull the latest image
docker pull ghcr.io/surahj/gomicrogen:latest

# Run gomicrogen
docker run --rm -it -v $(pwd):/workspace ghcr.io/surahj/gomicrogen:latest new my-service --module github.com/your-org/my-service

🎯 Quick Start

Create a new microservice with minimal configuration:

gomicrogen new my-service --module github.com/your-org/my-service

This will create a new microservice with:

Complete project structure
Docker configuration
Kubernetes manifests
Database migrations
API documentation
Hot reload setup

📖 Usage

Basic Command

gomicrogen new [service-name] [flags]

Required Flags

--module, -m: Go module name (e.g., github.com/your-org/service-name)

Optional Flags

Service Configuration

--description, -d: Service description
--version, -v: Service version (default: "1.0.0")
--author, -a: Author name
--port, -p: HTTP port (default: "8080")
--grpc-port, -g: gRPC port (default: "8081")
--env, -e: Environment (development, staging, production)

Database Configuration

--db-driver: Database driver (mysql, postgres, sqlite)
--db-url: Database connection URL
--db-host: Database host (default: "localhost")
--db-port: Database port (3306 for MySQL, 5432 for PostgreSQL)
--db-password: Database password

Redis Configuration

--redis-url: Redis connection URL
--redis-host: Redis host (default: "localhost")
--redis-port: Redis port (default: "6379")
--redis-db-number: Redis database number (0-15) (default: "0")
--redis-password: Redis password

Output Options

--output-dir, -o: Output directory (default: current directory)
--force: Force overwrite if service already exists
--git: Initialize Git repository with dev branch (default: true)
--go-mod: Run go mod init and go mod tidy (default: true)

Examples

Minimal Service

gomicrogen new user-service --module github.com/mycompany/user-service

Service with Custom Configuration

gomicrogen new payment-service \
  --module github.com/mycompany/payment-service \
  --description "Payment processing microservice" \
  --version "2.1.0" \
  --author "John Doe" \
  --port "3000" \
  --grpc-port "3001" \
  --db-driver "mysql" \
  --db-host "localhost" \
  --db-port "3306" \
  --db-password "secret" \
  --redis-host "localhost" \
  --redis-port "6379" \
  --env "development"

Service in Custom Directory

gomicrogen new auth-service \
  --module github.com/mycompany/auth-service \
  --output-dir /path/to/projects

Force Overwrite Existing Project

gomicrogen new my-service --module github.com/myorg/my-service --force

Skip Git and Go Module Initialization

gomicrogen new my-service --module github.com/myorg/my-service --git=false --go-mod=false

Getting Help

# General help
gomicrogen --help

# Command-specific help
gomicrogen new --help

# Show all available commands
gomicrogen help

📁 Generated Project Structure

service-name/
├── app/
│   ├── auth/           # Authentication middleware
│   ├── constants/      # Application constants
│   ├── controllers/    # HTTP controllers
│   ├── database/       # Database connection and models
│   ├── grpc/          # gRPC server and services
│   ├── library/       # Shared libraries and utilities
│   ├── models/        # Data models
│   ├── router/        # HTTP router setup
│   └── utils/         # Utility functions
├── cmd/               # Command-line tools
├── docs/              # API documentation
├── k8s/               # Kubernetes manifests
├── migrations/        # Database migrations
├── test/              # Test files
├── .gitignore         # Git ignore file
├── air.toml           # Hot reload configuration
├── docker-compose-local.yml  # Local development setup
├── Dockerfile         # Production Docker image
├── Dockerfile.dev     # Development Docker image
├── go.mod             # Go module file
├── go.sum             # Go dependencies checksum
├── main.go            # Application entry point
└── Makefile           # Build and deployment commands

🔧 Configuration

Environment Variables

The generated service supports the following environment variables:

# Database Configuration
DATABASE_USERNAME=your_username
DATABASE_HOST=localhost
DATABASE_PORT=3306
DATABASE_PASSWORD=your_password
DATABASE_NAME=your_database
DATABASE_MAX_CONNECTION=150
DATABASE_IDLE_CONNECTION=100
DATABASE_CONNECTION_LIFETIME=60

# Redis Configuration
REDIS_HOST=localhost
REDIS_PORT=6379
REDIS_DATABASE_NUMBER=0
REDIS_PASSWORD=your_redis_password

# Service Configuration
SYSTEM_HOST=0.0.0.0
SYSTEM_PORT=8080
SYSTEM_GRPC_PORT=8081
ENV=development

# Observability
UPTRACE_DSN=your_uptrace_dsn
BASE_URL=https://your-api-domain.com

Docker Compose

For local development, the generated service includes a docker-compose-local.yml file:

# Start the service locally
docker-compose -f docker-compose-local.yml up

# Build and start
docker-compose -f docker-compose-local.yml up --build

🚀 Getting Started with Generated Service

Navigate to the project directory:
```
cd your-service-name
```
Install dependencies:
```
go mod tidy
```

Set up environment variables:

cp .env.example .env
# Edit .env with your configuration

Run database migrations:
```
make migrate-up
```

Start the service:

# Development with hot reload
make dev

# Production
make run

# Or directly
go run main.go

🛠️ Development Commands

The generated service includes a comprehensive Makefile with useful commands:

# Development
make dev          # Run with hot reload using Air
make run          # Run the service
make build        # Build the binary
make test         # Run tests
make test-coverage # Run tests with coverage

# Database
make migrate-up   # Run database migrations
make migrate-down # Rollback database migrations
make migrate-create # Create new migration

# Docker
make docker-build # Build Docker image
make docker-run   # Run Docker container
make docker-stop  # Stop Docker container

# Kubernetes
make k8s-deploy   # Deploy to Kubernetes
make k8s-delete   # Delete from Kubernetes

# Utilities
make clean        # Clean build artifacts
make lint         # Run linter
make fmt          # Format code

📚 API Documentation

The generated service includes Swagger/OpenAPI documentation:

Start the service
Visit: http://localhost:8080/swagger/index.html

🔍 Observability

The generated service includes:

OpenTelemetry: Distributed tracing
Uptrace: Metrics and monitoring
Structured Logging: Using logrus

🐳 Docker Support

Development

# Build development image
docker build -f Dockerfile.dev -t my-service:dev .

# Run with docker-compose
docker-compose -f docker-compose-local.yml up

Production

# Build production image
docker build -t my-service:latest .

# Run production container
docker run -p 8080:8080 -p 8081:8081 my-service:latest

☸️ Kubernetes Deployment

The generated service includes Kubernetes manifests in the k8s/ directory:

# Deploy to Kubernetes
kubectl apply -f k8s/

# Check deployment status
kubectl get pods -l app=my-service

🤝 Contributing

Fork the repository
Create a feature branch (git checkout -b feature/amazing-feature)
Commit your changes (git commit -m 'Add amazing feature')
Push to the branch (git push origin feature/amazing-feature)
Open a Pull Request

📄 License

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

🆘 Troubleshooting

Common Issues

Installation fails
- Ensure you have write permissions to /usr/local/bin/ or use the one-line installer
- Check that curl/wget is available on your system
- Verify your internet connection can access GitHub
Go module initialization fails
- Check that Go is properly installed and in your PATH
- Ensure you have write permissions in the target directory
- Verify the module name follows Go module naming conventions
Database connection issues
- Verify database credentials and connection settings
- Ensure the database server is running and accessible
- Check that the database driver is supported (mysql, postgres, sqlite)
Port already in use
- Use different ports with --port and --grpc-port flags
- Check for existing services using the same ports
- Use netstat -tulpn | grep :8080 to check port usage
Git initialization fails
- Ensure Git is installed and configured
- Check that you have write permissions in the target directory
- Use --git=false to skip Git initialization if needed

Getting Help

Create an issue on GitHub
Check the existing issues for similar problems
Review the generated code and configuration files
Use gomicrogen --help for command-line help

🔗 Related Projects

Cobra - CLI framework for Go
Air - Live reload for Go apps
golang-migrate - Database migrations
Uptrace - Observability platform

Name		Name	Last commit message	Last commit date
Latest commit History 16 Commits
.github/workflows		.github/workflows
cmd		cmd
internal		internal
scripts		scripts
templates		templates
.gitignore		.gitignore
.goignore		.goignore
CHANGELOG.md		CHANGELOG.md
DEPLOYMENT.md		DEPLOYMENT.md
Dockerfile		Dockerfile
Makefile		Makefile
README.md		README.md
SETUP_SUMMARY.md		SETUP_SUMMARY.md
go.mod		go.mod
go.sum		go.sum
install-oneline.sh		install-oneline.sh
install.ps1		install.ps1
install.sh		install.sh
main.go		main.go

Folders and files

Latest commit

History

Repository files navigation

gomicrogen

🚀 Features

📋 Prerequisites

🛠️ Installation

Quick Install (Recommended)

Linux/macOS

Windows (PowerShell)

Manual Installation

Linux

macOS

Windows

From Source

Using Go Install

Using Docker

🎯 Quick Start

📖 Usage

Basic Command

Required Flags

Optional Flags

Service Configuration

Database Configuration

Redis Configuration

Output Options

Examples

Minimal Service

Service with Custom Configuration

Service in Custom Directory

Force Overwrite Existing Project

Skip Git and Go Module Initialization

Getting Help

📁 Generated Project Structure

🔧 Configuration

Environment Variables

Docker Compose

🚀 Getting Started with Generated Service

🛠️ Development Commands

📚 API Documentation

🔍 Observability

🐳 Docker Support

Development

Production

☸️ Kubernetes Deployment

🤝 Contributing

📄 License

🆘 Troubleshooting

Common Issues

Getting Help

🔗 Related Projects

About

Resources

Uh oh!

Stars

Watchers

Forks

Releases 3

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

Packages