Go REST API Boilerplate

Production-ready in 90 seconds. No headaches, just clean code.

GRAB is a Go boilerplate that doesn't waste your time — highly tested, Docker-ready, fully documented, AI-assistant optimized, with everything you need. Built for developers who want to code with AI, not fight it.

📖 Full Documentation • 🚀 Quick Start • ✨ Live Demo

---

🤖 AI-Friendly Development

GRAB is designed to work seamlessly with your favorite AI coding assistants:

Out-of-the-box AI integration with comprehensive guidelines for:

• GitHub Copilot (VS Code, GoLand, Visual Studio)
• Cursor IDE (with dedicated .cursor/rules/)
• Windsurf IDE (with dedicated .windsurf/rules/)
• JetBrains AI (via AGENTS.md standard)
• Any AI assistant supporting AGENTS.md standard

Note: GoLand users get dual AI support through both GitHub Copilot (via .github/copilot-instructions.md) and JetBrains AI (via AGENTS.md). No IDE-specific configuration needed.

AI assistants understand GRAB's Clean Architecture, Docker-first workflow, migration patterns, and testing conventions. Get intelligent code completions, accurate refactoring suggestions, and context-aware help.

📚 Learn More: AI-Friendly Development Guide

---

🕒 Why Waste Days on Setup?

You know the pain: Starting a new Go project means days of configuring Docker, wiring up authentication, setting up migrations, writing boilerplate code, and praying your hot-reload actually works.

GRAB changes that.

make quick-start  # ← One command. 90 seconds. You're building features.

This is the real deal. The production-grade boilerplate you wish you had from day one:

✅ Clean Architecture — Handler → Service → Repository (GO industry standard)
✅ AI-Optimized Guidelines — Built-in rules for GitHub Copilot, Cursor, Windsurf & AGENTS.md
✅ Security & JWT Auth — OAuth 2.0 BCP compliant with refresh token rotation, rate limiting, CORS
✅ Role-Based Access Control — Many-to-many RBAC with JWT integration and secure admin CLI
✅ Database Migrations — PostgreSQL with version control & rollback
✅ Comprehensive Tests — Unit + integration with CI/CD pipeline
✅ Interactive Docs — Auto-generated Swagger + Postman collection
✅ Structured Logging — JSON logs with request IDs and tracing
✅ Standardized API Responses — Consistent envelope format for all endpoints
✅ Structured Error Handling — Machine-readable error codes with details
✅ Production Docker — Multi-stage builds, health checks, optimized images
✅ Environment-Aware — Dev/staging/prod configs + Make automation & more
✅ Graceful Shutdown — Zero-downtime deployments with configurable timeouts
✅ Hot-Reload (2 seconds!) — Powered by Air, not magic

And that's just scratching the surface. Check the full documentation to see everything GRAB offers.

🏆 Built Following Go Standards

Not some random structure — follows official Go project layout + battle-tested community patterns from golang-standards/project-layout. The same architecture used by Gin, GORM, and production Go services.

🎯 Perfect For

• 🚀 Shipping Fast — Launch MVPs and production APIs in days, not weeks
• 👥 Team Projects — Consistent standards everyone understands
• 🏗️ Scaling Up — Architecture that grows with your business
• 📖 Learning Go — See how pros structure real-world applications

---

🚀 Quick Start

Get your API running in under 2 minutes:

Prerequisites

• Docker and Docker Compose
• Git

💡 Want to run without Docker? See the Manual Setup Guide in the documentation.

One-Command Setup ⚡

git clone https://github.com/vahiiiid/go-rest-api-boilerplate.git
cd go-rest-api-boilerplate
make quick-start

🎉 Done! Your API is now running at:

• API Base URL: http://localhost:8080/api/v1
• Swagger UI: http://localhost:8080/swagger/index.html
• Health Checks: http://localhost:8080/health • /health/live • /health/ready

Create Admin User:

make create-admin              # Interactive: prompts for email, name, password
make promote-admin ID=1        # Promote existing user to admin by ID

---

✨ See It In Action

Interactive Swagger Documentation

Open http://localhost:8080/swagger/index.html to explore and test all endpoints interactively.

Or Use Postman

Import the pre-configured collection from api/postman_collection.json with example requests and tests.

🚀 Ready to Build?

• 📖 Development Guide — Learn how to add models, routes, and handlers
• 💡 TODO List Tutorial — Complete step-by-step feature implementation from scratch

---

💎 What Makes GRAB Different?

Not Just Features — A Complete Development Experience

Most boilerplates give you code. GRAB gives you a professional development workflow.

🔐 Authentication That Actually Works

• OAuth 2.0 BCP compliant — JWT-based auth (HS256) with refresh token rotation and automatic reuse detection
• Enhanced security — Refresh tokens with family tracking, secure token invalidation, and breach detection
• Context helpers — Type-safe user extraction (no more casting nightmares)
• Password security — Bcrypt hashing with best-practice cost factor
• Rate limiting — Token-bucket protection against abuse built-in

👉 Authentication Guide | Context Helpers

🔑 Role-Based Access Control (RBAC)

• Many-to-many architecture — Flexible roles system with extensible permissions
• Secure admin CLI — Interactive admin creation with strong password enforcement (no defaults in code)
• JWT-integrated authorization — Roles embedded in tokens for server-side validation
• Protected endpoints — Middleware-based access control (RequireRole, RequireAdmin)
• Three-endpoint pattern — /auth/me (current user), /users/:id (specific), /users (admin list)
• Paginated user management — Admin-only user listing with filtering and search

👉 RBAC Guide

🗄️ Database Setup That Doesn't Fight You

• PostgreSQL + GORM — Production-grade ORM with relationship support

• golang-migrate — Industry-standard migrations with timestamp versioning

• Complete migration CLI — Create, apply, rollback with ease

  make migrate-create NAME=add_posts_table  # Create with timestamp
  make migrate-up                            # Apply all pending
  make migrate-down                          # Rollback last (safe)
  make migrate-down STEPS=3                  # Rollback multiple
  make migrate-status                        # Check current version
  make migrate-goto VERSION=<timestamp>      # Jump to specific version

• Safety features — Confirmation prompts, dirty state detection

• Transaction support — BEGIN/COMMIT wrappers for data integrity

• Connection pooling — Configured for performance out of the box

👉 Migrations Guide

🐳 Docker That Saves Your Sanity

• 2-second hot-reload — Powered by Air, actually works in Docker
• One command to rule them all — make quick-start handles everything
• Development & production — Separate optimized configs
• Multi-stage builds — Tiny production images (~20MB)

👉 Docker Guide

🏥 Production-Grade Health Checks

• Kubernetes-ready probes — Liveness (/health/live) and readiness (/health/ready) endpoints
• Database health monitoring — Response time tracking with pass/warn/fail thresholds
• RFC-compliant responses — Following IETF draft standards for health check format
• Zero-downtime deployments — Smart readiness checks for load balancer integration
• Extensible architecture — Easy to add custom health checkers (Redis, external APIs, etc.)

👉 Health Checks Guide

📚 Documentation That Exists (And Helps!)

• Auto-generated Swagger — Interactive API explorer at /swagger/index.html
• Full documentation site — Not just README, real guides at vahiiiid.github.io/go-rest-api-docs
• Step-by-step tutorials — Build a TODO app from scratch
• Postman collection — Import and test immediately

👉 Full Documentation

🧪 Tests That Give You Confidence

• Comprehensive coverage — Handlers, services, and repositories all tested
• In-memory SQLite — No external dependencies for tests
• Table-driven tests — Go idiomatic testing patterns
• CI/CD ready — GitHub Actions configured and working

👉 Testing Guide

📦 Standardized API Responses

• Consistent envelope format — All responses wrapped in {success, data, error, meta} structure
• JSend-inspired design — Industry best practice for API response formatting
• Type-safe responses — Predictable structure for frontend integration
• Metadata support — Pagination, timestamps, request IDs built-in

👉 API Response Format Guide

⚠️ Error Handling That Makes Sense

• Structured API errors — Machine-readable codes (NOT_FOUND, VALIDATION_ERROR, etc.)
• Detailed error info — Code, message, details, timestamp, path, request ID
• Validation details — Clear field-level error messages for bad requests
• Centralized middleware — Single error handler for consistent responses
• Rate limit errors — Includes retry_after for proper backoff logic

👉 Error Handling Guide

🏗️ Architecture That Scales

• Clean layers — Handler → Service → Repository (no shortcuts)
• Dependency injection — Proper DI, easy to mock and test
• Domain-driven — Organize by feature, not by layer
• Official Go layout — Follows golang-standards/project-layout

👉 Development Guide

---

🛠️ Development

With Docker (Recommended)

The easiest way to develop with hot-reload and zero setup:

make up        # Start containers with hot-reload
make logs      # View logs
make test      # Run all tests
make lint      # Check code quality
make lint-fix  # Auto-fix linting issues
make down      # Stop containers

What you get:

• 🔥 Hot-reload — Code changes reflect in ~2 seconds (powered by Air)
• 📦 Volume mounts — Edit code in your IDE, runs in container
• 🗄️ PostgreSQL — Database on internal Docker network
• 📚 All tools pre-installed — No Go installation needed on host

Database Migrations

Production-grade migrations using golang-migrate:

make migrate-create NAME=add_todos_table  # Create new migration
make migrate-up                            # Apply all pending
make migrate-down                          # Rollback last migration
make migrate-status                        # Check current version

For long-running migrations:

go run cmd/migrate/main.go up --timeout=30m --lock-timeout=1m

All environments use SQL migrations for consistency and safety.

👉 Complete Migration Guide

Without Docker

Want to run natively? You'll need Go 1.24+ installed.

make build-binary    # Build binary to bin/server
make run-binary      # Build and run (requires PostgreSQL on localhost)

👉 Full Setup Guide for native development

---

🚢 Deployment

Production-Ready From Day One

GRAB includes optimized production builds:

make docker-up-prod  # Start production containers

What's included:

• ✅ Multi-stage Docker builds (minimal image size)
• ✅ Production-grade health checks (liveness & readiness probes)
• ✅ Environment-based configuration
• ✅ No development dependencies
• ✅ Production logging

Deploy Anywhere

Ready for:

• AWS ECS/Fargate — Container orchestration
• Google Cloud Run — Serverless containers
• DigitalOcean App Platform — Platform-as-a-service
• Kubernetes — Self-managed orchestration
• Any VPS — Using Docker Compose

👉 Deployment Guide for step-by-step instructions

---

📖 Documentation

🌐 Full Documentation Site

📚 Read the Docs →

Complete guides covering everything:

• 🚀 Getting Started — Installation and configuration
• 💻 Development Guide — Building features
• 💡 TODO Tutorial — Step-by-step implementation
• 🐳 Docker Guide — Container workflows
• 🗄️ Migrations — Database schema management
• 🏥 Health Checks — Kubernetes probes and monitoring
• 🧪 Testing — Writing and running tests
• 📦 API Response Format — Standardized response envelope
• ⚠️ Error Handling — Structured API errors
• 📚 Swagger — API documentation
• ⚙️ Configuration — Environment setup

🤝 Contributing to Documentation

Documentation lives in a separate repository. To contribute:

1. Visit github.com/vahiiiid/go-rest-api-docs
2. Follow the contributing guidelines
3. Submit pull requests for improvements

For code contributions, see CONTRIBUTING.md

---

🤝 Contributing

We ❤️ contributions! See CONTRIBUTING.md for:

• Code style guidelines
• Pull request process
• Testing requirements
• Commit conventions

Quick Start

1. Fork the repository
2. Create a feature branch (git checkout -b feat/amazing-feature)
3. Make your changes
4. Run tests and linter (make lint-fix && make lint && make test)
5. Commit your changes (git commit -m 'feat: add amazing feature')
6. Push to the branch (git push origin feat/amazing-feature)
7. Open a Pull Request

---

🙏 Built With Amazing Tools

• Gin — Fast HTTP web framework
• GORM — Developer-friendly ORM
• golang-migrate — Database migration toolkit
• Viper — Configuration management
• golang-jwt — JWT implementation
• swaggo — Swagger documentation generator
• Air — Hot-reload for development

---

📄 License

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

---

💬 Support & Community

• 📖 Read the Documentation
• 🐛 Report Bugs
• 💬 Ask Questions
• ⭐ Star this repo if you find it helpful!

---

Made with ❤️ for the Go community

⭐ Star • 📖 Docs • 🐛 Issues • 💬 Discussions