{"id":15178820,"url":"https://github.com/highlyavailable/go-template","last_synced_at":"2026-03-07T16:34:32.568Z","repository":{"id":250342318,"uuid":"834128221","full_name":"highlyavailable/go-template","owner":"highlyavailable","description":"A structured Go app template with a Makefile for build automation, envconfig for environment management, Zap and lumberjack for logging with rotation/retention, OpenTelemetry and Prometheus for metrics/tracing, and Docker support. Includes a Gin server with health checks, Swagger docs, and various other integrations.","archived":false,"fork":false,"pushed_at":"2025-06-05T15:34:24.000Z","size":8850,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-10-26T17:49:12.889Z","etag":null,"topics":["docker","go","grafana","kafka","lumberjack","makefile","otel","prometheus","template","zap-logger"],"latest_commit_sha":null,"homepage":"","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/highlyavailable.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2024-07-26T13:30:48.000Z","updated_at":"2025-06-05T15:34:26.000Z","dependencies_parsed_at":"2024-09-23T10:30:56.566Z","dependency_job_id":"3a6520db-0adc-473f-93a4-c62eea6df37c","html_url":"https://github.com/highlyavailable/go-template","commit_stats":{"total_commits":48,"total_committers":2,"mean_commits":24.0,"dds":0.1875,"last_synced_commit":"1b05cecec72c0cea6ecd3386a081b3fed1e59ca6"},"previous_names":["highlyavailable/go-template"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/highlyavailable/go-template","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/highlyavailable%2Fgo-template","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/highlyavailable%2Fgo-template/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/highlyavailable%2Fgo-template/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/highlyavailable%2Fgo-template/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/highlyavailable","download_url":"https://codeload.github.com/highlyavailable/go-template/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/highlyavailable%2Fgo-template/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":30221511,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-03-07T14:02:48.375Z","status":"ssl_error","status_checked_at":"2026-03-07T14:02:43.192Z","response_time":53,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["docker","go","grafana","kafka","lumberjack","makefile","otel","prometheus","template","zap-logger"],"created_at":"2024-09-27T15:23:22.844Z","updated_at":"2026-03-07T16:34:32.542Z","avatar_url":"https://github.com/highlyavailable.png","language":"Go","readme":"# Go Template Project\n\nA ready-to-use Go template with DI, logging, configuration, database, HTTP server, observability, testing, and Docker support.\n\n## Overview\n\nThis template provides a solid foundation for building Go applications with:\n\n- **Dependency Injection**: Clean, testable architecture with proper DI container\n- **Structured Logging**: Both structured and unstructured logging with Zap\n- **Configuration Management**: Environment-based configuration with sensible defaults\n- **Database Integration**: PostgreSQL and Kafka support with interfaces\n- **HTTP Server**: Gin-based REST API with health checks and Swagger docs\n- **Observability**: OpenTelemetry tracing and Prometheus metrics\n- **Testing**: Comprehensive test coverage with proper mocking\n- **Docker Support**: Production-ready containerization\n\n## Getting Started\n\n### Prerequisites\n\n- Go 1.21+\n- Docker (optional, for databases and monitoring)\n- Make (for build automation)\n\n### Configuration\n\nThe application uses environment variables with defaults:\n\n```bash\n# Application\nGO_APP_APP_NAME=myapp\nGO_APP_ENV=development\nGO_APP_PORT=8080\n\n# Logging\nLOGGER_WRITE_STDOUT=true\nLOGGER_ENABLE_STACK_TRACE=false\nLOGGER_APP_LOG_PATH=./logs/app.log\nLOGGER_ERR_LOG_PATH=./logs/error.log\n```\n\n## Architecture\n\n### Project Structure\n\n```\ngoapp/\n├── api/                    # HTTP layer\n│   ├── handlers/          # HTTP handlers with DI\n│   └── routes/            # Route definitions\n├── cmd/                   # Application entrypoints\n│   ├── goapp/            # Main HTTP server\n├── internal/              # Internal packages (not importable)\n│   ├── config/           # Configuration management\n│   ├── container/        # Dependency injection container\n│   ├── db/              # Database implementations\n│   │   ├── postgres/    # PostgreSQL client\n│   │   └── kafka/       # Kafka client\n│   ├── logging/         # Logging implementation\n│   └── observability/   # OpenTelemetry setup\n├── pkg/                  # Public packages (reusable)\n│   └── clients/         # HTTP clients\n└── docs/                # Swagger documentation\n```\n\n### Guide\n\n- **pkg/ vs internal/**: `pkg/` contains reusable libraries, `internal/` contains app-specific code\n- **Interface-driven**: All major components implement interfaces for easy testing\n- **Dependency Injection**: No global state, all dependencies are injected\n- **Configuration**: Single source of truth with environment variable support\n- **Error Handling**: Proper error propagation with context\n\n## Features\n\n### Logging\n\nThe logging package supports both structured and unstructured logging:\n\n```go\n// Structured logging (recommended)\nlogger.Info(\"User created\", \n    logging.String(\"user_id\", \"123\"),\n    logging.String(\"email\", \"user@example.com\"))\n\n// Unstructured logging (for simple cases)\nlogger.Infof(\"User %s created with email %s\", userID, email)\n\n// Context logging\nuserLogger := logger.With(logging.String(\"user_id\", userID))\nuserLogger.Info(\"Processing user request\")\n```\n\n### Database\n\nPostgreSQL integration with proper error handling:\n\n```go\n// The database interface is injected into handlers\nfunc (h *Handler) CreateUser(c *gin.Context) {\n    // Use h.Database.DB() to get *sqlx.DB instance\n    user := \u0026User{}\n    err := h.Database.DB().Get(user, \"SELECT * FROM users WHERE id = $1\", userID)\n    if err != nil {\n        h.Logger.Error(\"Failed to fetch user\", logging.Error(err))\n        return\n    }\n}\n```\n\n### Health Checks\n\nBuilt-in health checks that verify:\n\n- Application status\n- Database connectivity\n- External service availability\n\n### Configuration\n\nType-safe configuration with validation:\n\n```go\ntype AppConfig struct {\n    Name        string `envconfig:\"APP_NAME\" default:\"goapp\"`\n    Env         string `envconfig:\"ENV\" default:\"development\"`\n    Port        int    `envconfig:\"PORT\" default:\"8080\"`\n}\n```\n\n## Development\n\n### Building\n\n```bash\n# Build for current platform\ngo build ./cmd/goapp\n\n# Build for Linux\nGOOS=linux go build ./cmd/goapp\n\n# Build with race detector\ngo build -race ./cmd/goapp\n```\n\n### Testing\n\n```bash\n# Run all tests\ngo test ./...\n\n# Run tests with coverage\ngo test -cover ./...\n\n# Run tests with race detector\ngo test -race ./...\n```\n\n### Docker\n\n```bash\n# Build image\ndocker build -t myapp .\n\n# Run with docker-compose\ndocker-compose up\n```\n\n## Extending the Template\n\n### Adding New Dependencies\n\n1. Update `internal/config/config.go` with new configuration\n2. Add the service interface to your package\n3. Update `internal/container/container.go` to initialize the new service\n4. Inject into handlers via the container\n\n### Adding New Endpoints\n\n1. Create handler methods in `api/handlers/`\n2. Update `api/routes/routes.go` to register routes\n3. Add Swagger documentation comments\n4. Generate docs: `swag init`\n\n### Adding Middleware\n\n```go\n// In routes.go\nrouter.Use(authMiddleware(container))\nrouter.Use(corsMiddleware())\n```\n\n## Production Considerations\n\n- Set `GO_APP_ENV=production` for optimized builds\n- Use proper secret management for sensitive configuration\n- Set up log aggregation (ELK stack, Fluentd, etc.)\n- Configure reverse proxy (nginx, Traefik)\n- Set up monitoring and alerting\n- Use database migrations for schema changes\n- Configure graceful shutdown timeouts appropriately\n\n## Monitoring\n\nThe template includes:\n\n- **Prometheus metrics**: Available at `/metrics`\n- **OpenTelemetry tracing**: Distributed tracing support\n- **Health checks**: Kubernetes-ready health endpoints\n- **Structured logging**: JSON formatted logs for aggregation\n\n## License\n\nThis template is provided as-is for creating new Go projects. Modify as needed for your use case.\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhighlyavailable%2Fgo-template","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fhighlyavailable%2Fgo-template","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhighlyavailable%2Fgo-template/lists"}