Go Project Template

A production-ready Go project template with best practices, standardized structure, and modern development tooling.

🚀 Features

• Modern Go Structure: Follows the Standard Go Project Layout
• Docker Support: Multi-stage Dockerfile for optimized production builds
• Dev Container: Pre-configured development environment with VS Code integration
• CI/CD Ready: GitHub Actions workflows and conventional commit guidelines
• Extensible Architecture: Pre-structured packages for common requirements:
  • Database connectivity (pkg/database/)
  • Message queue integration (pkg/queue/)
  • HTTP routing and middleware (internal/router/)
  • Audit logging and tracing (internal/)

📁 Project Structure

.
├── cmd/                    # Main applications for this project
├── internal/               # Private application and library code
│   ├── audit.go           # Audit logging functionality
│   ├── tracing.go         # Distributed tracing support
│   └── router/            # HTTP server and middleware
│       ├── server.go
│       └── middleware.go
├── pkg/                    # Public library code (safe to import)
│   ├── database/          # Database clients and connections
│   │   └── mongodb.go
│   └── queue/             # Message queue integrations
│       └── rabbitmq.go
├── example/               # Example applications and documentation
├── .devcontainer/         # VS Code dev container configuration
├── .github/               # GitHub workflows and templates
├── Dockerfile             # Multi-stage production build
├── go.mod                 # Go module definition
└── main.go                # Application entry point

🛠️ Getting Started

Prerequisites

• Go 1.24+ (or use the provided dev container)
• Docker (optional, for containerized development)

Using This Template

1. Create a new repository from this template:

   • Click "Use this template" on GitHub
   • Or clone directly: git clone https://github.com/uug-ai/templates-go.git your-project

2. Update module name:

   # Replace the module path in go.mod
   go mod edit -module github.com/yourusername/yourproject

3. Install dependencies:

   go mod download

4. Run the application:

   go run main.go

Development with Dev Container

This template includes a complete dev container configuration:

1. Open the project in VS Code
2. Install the "Dev Containers" extension
3. Click "Reopen in Container" when prompted
4. All tools and dependencies are automatically configured

🏗️ Building

Local Build

# Build for your current platform
go build -o app main.go

# Build with optimizations
go build -ldflags="-s -w" -o app main.go

Docker Build

# Build the Docker image
docker build \
  --build-arg project=myapp \
  --build-arg github_username=your-username \
  --build-arg github_token=your-token \
  -t myapp:latest .

# Run the container
docker run -p 8080:8080 myapp:latest

📦 Package Overview

internal/

Private application code that should not be imported by other projects:

• audit.go: Audit logging and compliance tracking
• tracing.go: OpenTelemetry or similar tracing integration
• router/: HTTP server setup and middleware stack

pkg/

Public packages that can be imported by external projects:

• database/: Database connection management (MongoDB, PostgreSQL, etc.)
• queue/: Message queue clients (RabbitMQ, Kafka, etc.)

cmd/

Entry points for different applications (CLIs, services, workers):

cmd/
├── server/      # Main HTTP server
├── worker/      # Background job processor
└── migrate/     # Database migration tool

🧪 Testing

# Run all tests
go test ./...

# Run tests with coverage
go test -cover ./...

# Run tests with verbose output
go test -v ./...

🔧 Configuration

The template supports environment-based configuration:

1. Copy .env to .env.local:

   cp .env .env.local

2. Update .env.local with your local settings (this file is gitignored)

3. Common environment variables:

   # Application
   APP_NAME=myapp
   APP_ENV=development
   PORT=8080
   
   # Database
   MONGODB_URI=mongodb://localhost:27017
   DATABASE_NAME=myapp
   
   # Message Queue
   RABBITMQ_URL=amqp://guest:guest@localhost:5672/

📝 Commit Guidelines

This project follows Conventional Commits:

<type>[optional scope]: <description>

[optional body]

[optional footer(s)]

Types: feat, fix, docs, style, refactor, perf, test, build, ci, chore

Examples:

feat(api): add user authentication endpoint
fix(database): resolve connection pooling issue
docs(readme): update installation instructions

See .github/copilot-instructions.md for detailed guidelines.

🤝 Contributing

1. Fork the repository
2. Create a feature branch: git checkout -b feat/amazing-feature
3. Commit your changes: git commit -m 'feat: add amazing feature'
4. Push to the branch: git push origin feat/amazing-feature
5. Open a Pull Request

📄 License

This template is available as open source. Modify and use it for your projects.

🔗 Resources

• Go Documentation
• Standard Go Project Layout
• Effective Go
• Conventional Commits
• Spec Kit – Spec-Driven Development

🌱 Spec-Driven Development with Spec Kit

This template ships with Spec Kit pre-installed in the dev container. Spec Kit lets you focus on what to build before how – specifications become the source of truth that drives AI-assisted implementation.

Quick Start

The specify CLI is already on your PATH inside the dev container.

# Verify the installation
specify check

# Initialize Spec Kit in this project (using GitHub Copilot)
specify init --here --ai copilot --ignore-agent-tools

# Or with another supported AI agent
specify init --here --ai claude --ignore-agent-tools

Note: Use --ignore-agent-tools inside the dev container to skip checks for agent CLI tools (e.g. Claude Code, Copilot CLI) that run on the host machine.

Typical Workflow

Once initialized, use the slash commands from your AI coding agent:

Step	Command	Purpose
1	/speckit.constitution	Define project principles and quality guidelines
2	/speckit.specify	Describe what you want to build (the what, not the how)
3	/speckit.plan	Create a technical implementation plan with your Go stack
4	/speckit.tasks	Break the plan into actionable tasks
5	/speckit.implement	Execute all tasks to build the feature

Example

# 1. Initialize Spec Kit
specify init --here --ai copilot --ignore-agent-tools

# 2. Open your AI agent and run:
#    /speckit.constitution Focus on idiomatic Go, table-driven tests, and clean package boundaries
#    /speckit.specify Build a REST API that exposes CRUD operations for a "projects" resource
#    /speckit.plan Use net/http, MongoDB for persistence, and the existing pkg/database package
#    /speckit.tasks
#    /speckit.implement

For the full methodology see the Spec-Driven Development guide.

💡 Tips

• Keep internal/ for code specific to your application
• Put reusable libraries in pkg/ if you plan to share them
• Use cmd/ for multiple binaries (services, CLI tools, etc.)
• Leverage the dev container for consistent development environments
• Follow the commit conventions for better changelog generation

---

Built with ❤️ by UUG.AI