scaffold

🚀 Scaffold: High-Performance Go Application Boilerplate

✨ Features

• 🔩 Advanced Build System: Powered by Taskfile for streamlined, repeatable builds and development tasks.
• ⚡ Hot-Reloading: Uses air for live-reloading during development, boosting productivity.
• 🧪 Comprehensive Testing: Integrated with gotestsum for beautiful, readable test outputs. Supports unit, integration, and benchmark tests.
• 📊 Advanced Code Coverage:
  • Standard HTML reports.
  • Enhanced function-level reports via gocov and gocov-html.
  • Interactive visual treemaps via go-cover-treemap.
• 🏆 Code Quality Assurance:
  • Linting with golangci-lint using a comprehensive ruleset.
  • Formatting with gofmt.
  • Static analysis with go vet.
• ⚙️ Configuration Management: Flexible configuration loading for different environments using viper.
• 🚀 Optimized Production Builds:
  • Cross-platform compilation for Linux, macOS, and Windows.
  • Aggressive size reduction using ldflags (-s -w).
  • UPX compression for ultra-small binaries (up to 85% size reduction).
• 🐳 Docker Ready: Multi-stage Dockerfile for small, secure production images.
• 🎛️ Centralized Binary Naming: Easily manage binary names from a single variable in the Taskfile.
• 📖 Self-Documenting: Includes a task help command for a detailed overview of all available tasks.

🛠️ Key Dependencies

Core Libraries

Development & Tooling

🏗️ Project Structure

scaffold/
├── build/                   # Build artifacts (binaries)
├── cmd/
│   └── server/              # Main application entrypoint
├── configs/                 # Configuration files (local.yml, prod.yml)
├── internal/                # Internal application code
│   ├── handler/
│   ├── middleware/
│   ├── model/
│   ├── repository/
│   └── service/
├── pkg/                     # Public packages
│   ├── config/
│   ├── helper/
│   ├── http/
│   └── log/
├── .air.toml                # Configuration for hot-reloading (air)
├── .golangci.yml            # Configuration for golangci-lint
├── Dockerfile               # Multi-stage Dockerfile
├── go.mod
├── go.sum
└── Taskfile.yml             # The heart of the build system

🏁 Getting Started

Prerequisites

• Go (version 1.22+ recommended)
• Task
• Docker (for containerized builds)
• UPX (optional, for binary compression)

Installation

1. Clone the repository:

   git clone https://github.com/thedatageek/scaffold.git
   cd scaffold
   

2. Install dependencies: The project uses Go Modules. The required tools and dependencies are installed automatically when you run a task for the first time. To install them manually:

   task deps
   

🚀 Usage: Available Tasks

This project uses Taskfile.yml as a modern alternative to Makefile. All commands are managed through task.

Run task --list for a quick overview or task help for detailed descriptions.

📦 Build Tasks

🏃 Development Tasks

🧪 Test Tasks

🔍 Code Quality Tasks

🐳 Docker Tasks

⚙️ Utility Tasks

⚙️ Configuration

Application configuration is managed by viper and loaded from the configs/ directory.

• configs/local.yml: Used for local development (task run, task dev).
• configs/prod.yml: Used for production runs (task run:prod).

You can specify a configuration file using the --config flag:

go run ./cmd/server --config=configs/local.yml

The system also supports a --validate-config flag to check if a configuration file is valid without running the server, used in the task config:validate task.

📦 Build & Deployment

Development Build

For a quick debug build with race detection enabled:

task build

This creates a binary at build/debug/scaffold-debug.

Production Release Builds

To create highly optimized and compressed binaries for distribution:

task build:release:all

This generates binaries for Linux, macOS, and Windows in their respective build/ subdirectories (e.g., build/linux/scaffold-amd64-linux).

Optimization Highlights:

• Stripped Symbols (-s -w): Removes debug information to reduce size.
• Static Linking: Creates self-contained binaries where possible.
• UPX Compression: Further compresses the binary, often resulting in an 80-85% size reduction. A 10MB binary can become ~1.5MB.

🔬 Testing and Coverage

This boilerplate offers a rich testing and coverage experience.

To run all tests:

task test

To generate and view the full suite of coverage reports:

task test:coverage:open

This command:

1. Runs tests and generates coverage data.
2. Creates three different reports in the reports/ directory:
   • coverage.html (standard)
   • coverage-enhanced.html (detailed)
   • coverage-treemap.svg (visual)
3. Starts a local web server on port 8080.
4. Opens your browser to view the reports.

🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

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

📜 License

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