goinit

GoInit - Go Gin API Starter Template & Generator

A comprehensive Go API starter template built with Gin framework, featuring authentication, user management, real-time communication, and a CLI tool to generate n## 🚀 Quick Start

Once installed, here's how to get started quickly:projects from the template.

🎯 What's Included

✅ Core Features

• Authentication & Authorization

  • JWT-based authentication with refresh tokens
  • Session management with cookies
  • Password reset functionality
  • Role-based access control (admin/user)

• User Management

  • User registration and login
  • Profile management
  • User roles and permissions
  • Admin user controls

• Real-time Communication

  • Server-Sent Events (SSE) for notifications
  • WebSocket support for bidirectional communication
  • Real-time event streaming

• Database Support

  • SQLite (default, file-based)
  • MySQL
  • PostgreSQL
  • GORM ORM with auto-migration

• Email Integration

  • SMTP email sending
  • Local email logging for development
  • HTML email templates

• Storage Solutions

  • Local file storage
  • S3-compatible storage (AWS S3, MinIO, etc.)

• API Documentation

  • Swagger/OpenAPI 3.0 documentation
  • Auto-generated API docs
  • Interactive API testing

• Project Generator CLI

  • Interactive project setup
  • Customizable configuration
  • Automated dependency management
  • Cross-platform builds

🏗️ Architecture

• Clean Architecture with separation of concerns
• Dependency Injection container
• Repository Pattern for data access
• Service Layer for business logic
• Middleware for cross-cutting concerns
• Automated Git Hooks for template synchronization

� Installation

GoInit can be installed and used in several ways depending on your needs.

Prerequisites

• Go 1.21+ - Download here
• Git - For cloning the repository
• Optional: Docker for containerized development

Method 1: Install CLI Generator (Recommended)

From Source

# Clone the repository
git clone https://github.com/SOG-web/goinit/goinit.git
cd goinit

# Run the installation script
chmod +x install.sh
./install.sh

# Verify installation
goinit --version

From Pre-built Binaries

1. Go to Releases

2. Download the appropriate binary for your platform:

   • goinit-linux-amd64 (Linux)
   • goinit-darwin-amd64 (macOS Intel)
   • goinit-darwin-arm64 (macOS Apple Silicon)
   • goinit-windows-amd64.exe (Windows)

3. Make executable and install:

   # Linux/macOS
   chmod +x goinit-*
   sudo mv goinit-* /usr/local/bin/goinit
   
   # Windows: Move to a directory in your PATH
   

4. Verify installation:

   goinit --version
   

Method 2: Use Template Directly

Clone and Setup

# Clone the repository
git clone https://github.com/SOG-web/goinit/goinit.git
cd goinit/gin

# Install Go dependencies
go mod tidy

# Copy environment configuration
cp .env.example .env

# Edit configuration (optional)
nano .env  # or your preferred editor

Docker Installation

# Clone repository
git clone https://github.com/SOG-web/goinit/goinit.git
cd goinit/gin

# Start with Docker Compose
docker-compose up --build

# Or build manually
docker build -t goinit-api .
docker run -p 8080:8080 --env-file .env goinit-api

Method 3: Go Install (Recommended)

# Install CLI generator directly
go install github.com/SOG-web/goinit@latest

# Generate a new project
goinit

# Follow the interactive prompts to configure your project

💡 Note: After installation, the CLI tool is available as goinit command.

Verification

After installation, verify everything works:

# Check CLI generator
goinit --help

# Test template (if using directly)
cd gin
go run cmd/api/main.go
# Should start server on http://localhost:8080

Post-Installation Setup

Environment Configuration

Edit .env file with your settings:

# Server
PORT=8080
PUBLIC_HOST=http://localhost:8080

# Database
DB_DRIVER=sqlite
DB_NAME=myapp.db

# Authentication
JWT_SECRET=your-super-secret-jwt-key-here
SESSION_SECRET=your-session-secret-here

# Email (optional)
USE_LOCAL_EMAIL=true  # For development

Database Setup

For production databases:

# SQLite (default - no setup needed)
# Files are created automatically

# MySQL
mysql -u root -p
CREATE DATABASE myapp;
GRANT ALL PRIVILEGES ON myapp.* TO 'user'@'localhost' IDENTIFIED BY 'password';

# PostgreSQL
psql -U postgres
CREATE DATABASE myapp;
CREATE USER myuser WITH PASSWORD 'password';
GRANT ALL PRIVILEGES ON DATABASE myapp TO myuser;

�🚀 Quick Start

Generate New Project (Fastest)

# Generate a new project
goinit

# Follow the interactive prompts
# Your project will be ready in minutes!

Use Template Directly

# Navigate to template
cd gin

# Quick start with default settings
go run cmd/api/main.go

# Visit http://localhost:8080/docs for API documentation

Docker Quick Start

cd gin
docker-compose up --build

💡 Tip: See the Installation section above for detailed setup instructions.

📁 Project Structure

Repository Structure

This repository contains both the template and the CLI generator:

goinit/
├── gin/                     # 🏗️  API Template Source
│   ├── cmd/api/            # Application entry point
│   ├── config/             # Configuration management
│   ├── internal/           # Internal application code
│   ├── api/                # HTTP handlers and routes
│   ├── docs/               # API documentation
│   └── docker/             # Docker configuration
├── .github/workflows/      # � GitHub Actions CI/CD
├── main.go                 # CLI generator entry point
├── go.mod                  # Go module for CLI generator
├── install.sh              # Installation script
└── README.md               # This file

Generated Project Structure

When you use the CLI generator, it creates a new project with this structure:

your-project/
├── cmd/api/                 # Application entry point
├── config/                  # Configuration management
├── internal/
│   ├── app/                # Application services
│   ├── data/               # Data layer (repositories)
│   ├── domain/             # Domain models
│   ├── lib/                # Shared libraries
│   │   ├── email/          # Email service
│   │   ├── jwt/            # JWT utilities
│   │   ├── pwreset/        # Password reset
│   │   └── storage/        # File storage
│   └── server/             # Server setup
├── api/                    # HTTP handlers and routes
│   ├── common/
│   │   ├── dto/            # Data transfer objects
│   │   └── middleware/     # HTTP middleware
│   └── protocol/
│       ├── http/
│       │   ├── handler/    # HTTP handlers
│       │   ├── router/     # Route setup
│       │   └── routes/     # Route definitions
│       ├── sse/            # Server-Sent Events
│       └── ws/             # WebSocket handlers
├── docs/                   # API documentation
├── docker/                 # Docker configuration
├── .env.example           # Environment template
└── go.mod                 # Go module file

🔧 Configuration

The application uses environment variables for configuration. Key settings:

Server

PORT=8080
PUBLIC_HOST=http://localhost:8080
GIN_MODE=debug

Database

DB_DRIVER=sqlite          # sqlite, mysql, postgres
DB_NAME=myapp
DB_USER=root
DB_PASSWORD=password
DB_HOST=localhost
DB_PORT=3306

Authentication

JWT_SECRET=your-jwt-secret
SESSION_SECRET=your-session-secret
USE_DATABASE_JWT=false    # true for database, false for Redis

Email

EMAIL_HOST=smtp.gmail.com
EMAIL_PORT=587
EMAIL_USERNAME=your-email@gmail.com
EMAIL_PASSWORD=your-app-password
USE_LOCAL_EMAIL=true      # true for development logging

Real-time Features

REDIS_ADDR=localhost:6379  # For JWT blacklist and sessions

📡 API Endpoints

Authentication

• POST /api/auth/register/ - User registration
• POST /api/auth/login/ - User login
• GET /api/auth/logout/ - User logout
• POST /api/auth/change-password/ - Change password
• POST /api/auth/password-reset/request/ - Request password reset
• POST /api/auth/password-reset/confirm/ - Confirm password reset

User Management

• GET /api/user/profile/ - Get user profile
• PUT /api/user/profile/ - Update user profile
• POST /api/user/profile/image/ - Upload profile image

Real-time

• GET /api/sse/events - Server-Sent Events stream
• GET /api/sse/notifications - Notification SSE stream
• GET /api/ws/connect - WebSocket connection

Admin (requires admin role)

• GET /api/admin/users/ - List all users
• GET /api/admin/stats/ - User statistics
• PUT /api/admin/users/:id/activate/ - Activate user
• PUT /api/admin/users/:id/deactivate/ - Deactivate user

Health Check

• GET /health - Server health check

🔐 Authentication

The API supports multiple authentication methods:

JWT Bearer Token

curl -H "Authorization: Bearer <jwt-token>" \
     http://localhost:8080/api/user/profile/

Session Cookies

Session cookies are automatically managed by the session middleware.

📧 Email Templates

The application includes email templates for:

• User registration verification
• Password reset
• Welcome emails
• Admin notifications

🗄️ Database Migrations

The application uses GORM's auto-migration feature. Models are automatically migrated on startup.

🧪 Testing

# Run all tests
go test ./...

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

# Run specific test
go test -run TestUserService ./internal/app/user/

� GitHub Actions & Releases

This project includes automated CI/CD pipelines:

Automated Releases

• Trigger: Push a version tag (e.g., v1.0.0)
• Builds: Cross-platform binaries for Linux, macOS (Intel/Apple Silicon), and Windows
• Artifacts: Automatically uploaded to GitHub Releases
• Workflow: .github/workflows/release.yml

Creating a Release

# Create and push a version tag
git tag v1.0.0
git push origin v1.0.0

# GitHub Actions will automatically:
# 1. Build binaries for all platforms
# 2. Create release archives
# 3. Upload to GitHub Releases

Development Workflow

• Pre-commit hooks: Automatically sync template files
• Pre-push hooks: Ensure template consistency before pushing
• Automated testing: Run tests on all platforms
• Code quality: Automated linting and formatting

� Docker Support

Development

# From the template directory
cd gin
docker-compose up --build

Production

# From the template directory
cd gin

# Build production image
docker build -f Dockerfile -t my-gin-api .

# Run with environment
docker run -p 8080:8080 --env-file .env my-gin-api

�📚 API Documentation

When running the generated project, visit: http://localhost:8080/docs/

The documentation is auto-generated from code comments using Swagger.

🔧 Development

Adding New Features

1. Create domain models in internal/domain/
2. Implement repository in internal/data/
3. Add service logic in internal/app/
4. Create HTTP handler in api/protocol/http/handler/
5. Add routes in api/protocol/http/routes/
6. Register dependencies in internal/di/container.go

Git Hooks

This project includes automated Git hooks for template synchronization:

• Pre-commit: Automatically copies updated template files before commits
• Pre-push: Ensures template consistency before pushing changes
• Location: .git/hooks/ (automatically installed)

The hooks ensure that the CLI generator always uses the latest template files.

🤝 Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests
5. Update documentation
6. Submit a pull request

📄 License

This project is licensed under the MIT License.

🙏 Acknowledgments

• Gin Web Framework - HTTP web framework
• GORM - ORM library
• JWT - JSON Web Tokens
• Swagger - API documentation
• Gorilla WebSocket - WebSocket implementation
• GoMail - Email sending

Repository: https://github.com/SOG-web/goinit/goinit
Happy coding! 🎉

For questions or issues, please open a GitHub issue.