Golang Gin Clean Starter

You can join in the development (Open Source). Let's Go!!!

Introduction 👋

This project implements Clean Architecture principles with the Controller–Service–Repository pattern. This approach emphasizes clear separation of responsibilities across different layers in Golang applications. The architecture helps keep the codebase clean, testable, and scalable by dividing application logic into distinct modules with well-defined boundaries.

Quick Start 🚀

Prerequisites

• Go Version >= go 1.20
• PostgreSQL Version >= version 15.0

Installation

1. Clone the repository or Use This Template

   git clone https://github.com/Caknoooo/go-gin-clean-starter.git

2. Navigate to the project directory:

   cd go-gin-clean-starter

3. Copy the example environment file and configure it:

   cp .env.example .env

4. Install dependencies:

   make dep

Running the Application 🏃‍♂️

There are two ways to run the application:

Option 1: With Docker

1. Configure .env with your PostgreSQL credentials:

   DB_HOST=localhost
   DB_USER=postgres
   DB_PASS=your_password
   DB_NAME=your_database
   DB_PORT=5432

2. Build and start Docker containers:

   make init-docker

3. Run migrations and seeders:

   make migrate-seed-docker

4. The application will be available at http://localhost:<port>

Docker Migration Commands:

make migrate-docker                                 # Run migrations in Docker
make migrate-status-docker                          # Show migration status in Docker
make migrate-rollback-docker                        # Rollback last batch in Docker
make migrate-rollback-batch-docker batch=<number>   # Rollback batch in Docker
make migrate-rollback-all-docker                    # Rollback all in Docker
make migrate-create-docker name=<name>              # Create migration in Docker

Option 2: Without Docker

1. Configure .env with your PostgreSQL credentials:

   DB_HOST=localhost
   DB_USER=postgres
   DB_PASS=your_password
   DB_NAME=your_database
   DB_PORT=5432

2. Run the application:

   make migrate      # Run migrations
   make seed         # Run seeders (optional)
   make migrate-seed # Run Migrations + Seeder
   make run          # Start the application

Available Make Commands 🚀

The project includes a comprehensive Makefile with the following commands:

Development Commands

make dep          # Install and tidy dependencies
make run          # Run the application locally
make build        # Build the application binary
make run-build    # Build and run the application

Migration Commands

make migrate                                # Run all pending migrations
make migrate-status                         # Show migration status
make migrate-rollback                       # Rollback the last batch
make migrate-rollback-batch batch=<number>  # Rollback specific batch
make migrate-rollback-all                   # Rollback all migrations
make migrate-create name=<migration_name>   # Create new migration file

Migration Examples:

make migrate                                 # Run migrations
make migrate-status                          # Check migration status
make migrate-rollback                        # Rollback last batch
make migrate-rollback-batch batch=2          # Rollback batch 2
make migrate-rollback-all                    # Rollback all migrations
make migrate-create name=create_posts_table  # Create migration with entity

Note: When creating a migration with format create_*_table, the system will automatically:

• Create the entity file in database/entities/
• Add the entity to the migration file
• Add the entity to database/migration.go AutoMigrate section

Module Generation Commands

make module name=<module_name>  # Generate a new module with all necessary files

Example:

make module name=product

This command will automatically create a complete module structure including:

• Controller (product_controller.go)
• Service (product_service.go)
• Repository (product_repository.go)
• DTO (product_dto.go)
• Validation (product_validation.go)
• Routes (routes.go)
• Test files for all components
• Query directory (for custom queries)

Advanced Usage 🔧

Running Migrations, Seeders, and Scripts

You can run migrations, seed the database, and execute scripts while keeping the application running:

go run cmd/main.go --migrate:run --seed --run --script:example_script

Available flags:

• --migrate or --migrate:run: Apply all pending migrations
• --migrate:status: Show migration status
• --migrate:rollback: Rollback the last batch
• --migrate:rollback <batch_number>: Rollback specific batch
• --migrate:rollback:all: Rollback all migrations
• --migrate:create:<migration_name>: Create new migration file
• --seed: Seed the database with initial data
• --script:example_script: Run the specified script (replace example_script with your script name)
• --run: Keep the application running after executing the commands above

Individual Commands

Database Migration

go run cmd/main.go --migrate:run                        # Run all pending migrations
go run cmd/main.go --migrate:status                     # Show migration status
go run cmd/main.go --migrate:rollback                   # Rollback last batch
go run cmd/main.go --migrate:rollback 2                 # Rollback batch 2
go run cmd/main.go --migrate:rollback:all               # Rollback all migrations
go run cmd/main.go --migrate:create:create_posts_table  # Create migration

Migration System Features:

• Batch-based migrations: Similar to Laravel, migrations are grouped in batches
• Automatic entity creation: When creating migration with format create_*_table, the system will:
  • Automatically create entity file in database/entities/
  • Add entity to migration file's AutoMigrate
  • Add entity to database/migration.go AutoMigrate section
• Rollback support: Rollback by batch or rollback all migrations
• Status tracking: View which migrations have been run and their batch numbers

Database Seeding

go run cmd/main.go --seed

This command will populate the database with initial data using the seeders defined in your application.

Script Execution

go run cmd/main.go --script:example_script

Replace example_script with the actual script name in script.go at the script folder.

Note: If you need the application to continue running after performing migrations, seeding, or executing a script, always append the --run option.

Logs Feature 📋

The application includes a built-in logging system that allows you to monitor and track system queries. You can access the logs through a modern, user-friendly interface.

Accessing Logs

To view the logs:

1. Make sure the application is running
2. Open your browser and navigate to:

http://your-domain/logs

Features

• Monthly Filtering: Filter logs by selecting different months
• Real-time Refresh: Instantly refresh logs with the refresh button
• Expandable Entries: Click on any log entry to view its full content
• Modern UI: Clean and responsive interface with glass-morphism design

📖 Documentation

API Documentation

Explore the available endpoints and their usage in the Postman Documentation. This documentation provides a comprehensive overview of the API endpoints, including request and response examples.

Contributing

We welcome contributions! The repository includes templates for issues and pull requests to standardize contributions and improve the quality of discussions and code reviews.

• Issue Template: Helps in reporting bugs or suggesting features by providing a structured format
• Pull Request Template: Guides contributors to provide clear descriptions of changes and testing steps

🤝 Contributing

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

🌟 Star History

📄 License

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

🙏 Acknowledgments

• Gin Web Framework
• GORM
• Samber/do for dependency injection
• Go Playground Validator
• Testify for testing