Skip to main content

​
Prerequisites

Before setting up the project locally, ensure you have the following installed:
  • Go: Version 1.22.2 or higher
  • Tailwind CSS: For styling compilation
  • Templ: For Go template generation
  • Air: For hot-reloading during development (optional)
  • MongoDB: For database (or use Docker Compose)

​
Environment Configuration

1

Create environment file

Create a .env file in the project root with the following variables:
DB_URL=mongodb://localhost:27017/trivia
PORT=8080
LOG_LEVEL=debug
ENV=dev
The load_env.sh script will automatically load these variables when using Makefile commands.
2

Install dependencies

Download all Go module dependencies:
go mod download
go mod verify
3

Choose your development workflow

You have several options for running the application locally:Use Air for automatic reloading on code changes. This will also generate templates automatically:
make air
This command:
  • Loads environment variables from .env
  • Watches for changes in .go, .templ, .html files
  • Automatically runs templ generate before building
  • Rebuilds and restarts the server on changes
Air is configured to exclude test files and generated template files from the build.

​
Option 2: Run Directly

Run the application without hot-reload:
make run
This runs go run ./cmd/web/main.go with environment variables loaded.

​
Option 3: Development with Live CSS/Template Updates

For frontend-heavy development, run these commands in separate terminals:Terminal 1 - Watch Tailwind CSS:
make tailwind
Terminal 2 - Watch Templ templates:
make templ
Terminal 3 - Run the application:
make air

​
Building the Application

To create a production build: 
make build
This compiles the application to ./bin/web.

​
Testing

make test
The coverage target generates a coverage report and displays function-level coverage statistics.

​
Project Structure

Key directories for local development:
  • cmd/web/main.go - Application entry point
  • internal/ - Internal application code
  • internal/config/ - Configuration management
  • internal/web/static/css/ - Stylesheets (Tailwind)
  • .air.toml - Air configuration for hot-reload

​
Troubleshooting

If you encounter port conflicts, Air is configured to kill any process using port 8080 before starting. You can modify this in .air.toml if needed.

​
Common Issues

Environment variables not loading:
  • Ensure .env file exists in the project root
  • Check that load_env.sh has execute permissions
  • Verify all required variables are set (DB_URL, PORT, LOG_LEVEL, ENV)
Template generation errors:
  • Install Templ CLI: go install github.com/a-h/templ/cmd/templ@latest
  • Run templ generate manually to see detailed errors
Database connection issues:
  • Ensure MongoDB is running on the configured port
  • Verify the DB_URL connection string format
  • Check MongoDB authentication credentials if using auth

​
Next Steps

Docker Deployment

Deploy with Docker Compose including MongoDB, Prometheus, and Grafana

Configuration

Learn about all available environment variables and settings

Build docs developers (and LLMs) love

Get started for freeTalk to us