---

About

A production-ready template for modern web applications using The Modern Go Stack - a cohesive technology stack for building high-performance, maintainable applications. Creates single, self-contained binaries with zero external dependencies.

Key Features:

• Echo v4 + Templ + HTMX 2.x: High-performance web framework with type-safe templates and dynamic UX
• SQLC + SQLite + Pure Go Driver: Type-safe database operations with zero CGO dependencies
• Enterprise Security: CSRF protection, input sanitization, structured error handling, request tracing
• Mage Build System: Go-based automation with comprehensive quality checks
• Production Ready: Rate limiting, CORS, secure headers, graceful shutdown
• Developer Experience: Hot reload with Air, database migrations with Goose, multi-source config

Tech Stack

Layer	Technology	Purpose
Language	Go 1.24+	Latest performance & language features
Framework	Echo v4	High-performance web framework
Templates	Templ	Type-safe Go HTML components
Frontend	HTMX 2.x	Dynamic interactions with smooth UX
CSS	Pico.css v2	Semantic CSS with dark/light themes
Logging	slog	Structured logging with JSON output
Database	SQLite	Self-contained, serverless database
Queries	SQLC	Generate type-safe Go from SQL
DB Driver	modernc.org/sqlite	Pure Go, CGO-free SQLite driver
Assets	Go Embed	Single binary with embedded resources
Config	Koanf	Multi-source configuration management
Migrations	Goose	Database migration management
Build	Mage	Go-based build automation
Hot Reload	Air	Development server with live reload

---

Quick Start

# Clone and setup
git clone https://github.com/dunamismax/go-web-server.git
cd go-web-server
go mod tidy

# Install development tools and dependencies
mage setup

# Start development server with hot reload
mage dev

# Or build and run production binary
mage run

# Server starts at http://localhost:8080

Requirements:

• Go 1.24+
• Mage build tool (go install github.com/magefile/mage@latest)

Note: First run of mage setup installs all development tools automatically.

Documentation

📚 Complete Documentation - Comprehensive guides for development, deployment, security, and architecture.

---

Mage Commands

Run mage help to see all available commands and their aliases.

Development:

mage setup (s)        # Install tools and dependencies
mage generate (g)     # Generate sqlc and templ code
mage dev (d)          # Start development server with hot reload
mage run (r)          # Build and run server

Database:

mage migrate (m)      # Run database migrations up
mage migrateDown      # Roll back last migration
mage migrateStatus    # Show migration status

Quality & Production:

mage fmt (f)          # Format code with goimports and tidy modules
mage vet (v)          # Run go vet static analysis
mage lint (l)         # Run golangci-lint comprehensive linting
mage vulncheck (vc)   # Check for security vulnerabilities
mage quality (q)      # Run all quality checks
mage ci               # Complete CI pipeline
mage clean (c)        # Clean build artifacts

Applications

Web Demo (localhost:8080)

Interactive user management application demonstrating:

• CRUD operations with type-safe database queries and CSRF protection
• Real-time updates via HTMX with smooth page transitions
• Responsive design with automatic dark/light theme switching
• Enterprise security with input sanitization and structured error handling

Project Structure

go-web-server/
├── cmd/web/              # Application entry point
├── docs/                 # Complete documentation
├── internal/
│   ├── config/           # Koanf configuration management
│   ├── handler/          # HTTP handlers with Echo routes
│   ├── middleware/       # Security, validation, error handling
│   ├── store/            # Database layer with SQLC
│   │   └── migrations/   # Goose database migrations
│   ├── ui/               # Static assets (embedded)
│   └── view/             # Templ templates and components
├── bin/                  # Compiled binaries
├── magefile.go          # Mage build automation
├── .golangci.yml        # Linter configuration
└── sqlc.yaml            # SQLC configuration

---

Production Deployment

Single Binary

mage build  # Creates optimized binary in bin/server (~11MB)

The binary includes embedded Pico.css, HTMX, Templ templates, and SQLite database. Zero external dependencies, single file deployment with instant startup.

Environment Variables

Koanf supports multiple configuration sources (JSON, YAML, TOML files + environment variables):

• SERVER_PORT: Server port (default: 8080)
• SERVER_HOST: Server host (default: "")
• DATABASE_URL: SQLite database file (default: data.db)
• DATABASE_RUN_MIGRATIONS: Auto-run database migrations (default: true)
• APP_ENVIRONMENT: Environment mode (default: development)
• APP_LOG_LEVEL: Logging level - debug, info, warn, error (default: info)
• APP_LOG_FORMAT: Log format - text or json (default: text)
• APP_DEBUG: Enable debug mode (default: false)
• SECURITY_ENABLE_CORS: Enable CORS middleware (default: true)

Key Features Demonstrated

Modern Web Stack:

• Echo v4 framework with comprehensive middleware stack
• Type-safe Templ templates with reusable components
• HTMX 2.x dynamic interactions with smooth page transitions
• Pico.css v2 semantic styling with automatic dark/light themes
• SQLC type-safe database queries with pure Go SQLite driver
• Structured logging with slog and configurable JSON output

Developer Experience:

• Hot reloading with Air for rapid development
• Comprehensive error handling with structured logging
• Static analysis suite (golangci-lint, govulncheck, go vet)
• Mage build automation with goimports and templ formatting
• Single-command CI pipeline with quality checks

Production Ready:

• Enterprise security with CSRF protection and input sanitization
• Structured error handling with request tracing and monitoring
• Multi-source configuration with Koanf (JSON, YAML, ENV)
• Database migrations with Goose and graceful shutdown
• Single binary deployment (~11MB) with embedded assets
• Zero external dependencies and CGO-free compilation

---

License

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

---

The Modern Go Stack
_{Echo v4 • Templ • HTMX 2.x • Pico.css v2 • SQLC • SQLite • slog • Koanf • Goose • Mage • Air}

---

"The "Modern Go Stack" is a powerful and elegant solution that aligns beautifully with Go's core principles. It is an excellent starting point for many new projects, and any decision to deviate from it should be driven by specific, demanding requirements." - Me

---