Building the Project

Prerequisites

Before building BookMe, ensure you have:

Go 1.22+ installed
PostgreSQL 14+ running
Make installed (optional but recommended)
Environment variables configured (see .env.example)

The project uses Go 1.25.7 as specified in go.mod:3, but Go 1.22+ is the minimum requirement.

Quick Start

Install Dependencies

Download and install all Go dependencies:

make deps

This runs:

go mod download - Downloads dependencies
go mod tidy - Cleans up unused dependencies

Set Up Environment

Copy the example environment file:

cp .env.example .env

Edit .env with your configuration (see Environment Setup).

Run Database Migrations

Apply database schema:

goose -dir sql/schema postgres "your-db-url" up

Run the Server

Start the development server:

make run

Server starts at http://localhost:8080

Build Commands

Available Make Targets

The Makefile provides convenient commands for common tasks:

# Run with hot reload (requires air)
make dev

# Run without hot reload
make run

Detailed Build Process

Building the Binary

The build command is defined in Makefile:12-15:

make build

This creates a binary at bin/book-me. Run it directly:

./bin/book-me

The binary is self-contained and can be deployed to any Linux/macOS system with the same architecture. Make sure to include your .env file or set environment variables.

Running in Development

Standard Run

make run

Executes go run ./cmd/server, which compiles and runs the application.

Hot Reload Development

For automatic reloading on file changes:

Install Air:

go install github.com/cosmtrek/air@latest

Run with hot reload:
```
make dev
```

Air watches for file changes and automatically rebuilds the server.

Code Generation

SQLC - Type-Safe Database Queries

BookMe uses SQLC to generate Go code from SQL queries.

When to Regenerate

Run make sqlc after:

Adding new SQL queries in sql/queries/
Modifying existing queries
Changing database schema in sql/schema/

SQLC Workflow

Write SQL Query

Add your query to the appropriate file in sql/queries/:

sql/queries/users.sql

-- name: GetUserByID :one
SELECT * FROM users WHERE id = $1;

Generate Go Code

Run the generator:

make sqlc

Use Generated Code

SQLC creates type-safe functions in internal/database/:

user, err := db.GetUserByID(ctx, userID)

Generated files are committed to version control. This ensures consistent builds without requiring SQLC to be installed in production environments.

Code Formatting

Format Go Code

make fmt

Runs go fmt ./... to format all Go files according to standard conventions.

Linting

The project uses golangci-lint with strict rules defined in .golangci.yml:1-58. Run the linter:

golangci-lint run

Enabled Linters

The configuration includes:

errcheck - Checks for unchecked errors
govet - Reports suspicious constructs
staticcheck - Advanced analysis
gosec - Security issues
revive - Style and correctness
bodyclose - HTTP response body leaks
errorlint - Proper error handling
exhaustive - Missing switch cases

Test files have relaxed linting rules (.golangci.yml:51-54) to allow for more flexible testing patterns.

Build Configuration

Binary Output

Build configuration from Makefile:14:

go build -o bin/book-me ./cmd/api

Note: The Makefile references ./cmd/api, but the actual directory is ./cmd/server. If the build fails, update the Makefile to use the correct path.

Application Entry Point

The main function is in cmd/server/main.go:22-26:

func main() {
    if err := run(); err != nil {
        slog.Error("server failed", "error", err)
        os.Exit(1)
    }
}

The run() function handles:

Configuration loading
Logger initialization
Database connection
API setup
HTTP server start
Graceful shutdown

Environment-Specific Builds

Development Build

No special flags needed:

go build -o bin/book-me ./cmd/server

Production Build

Optimize binary size and disable debug info:

go build -ldflags="-s -w" -o bin/book-me ./cmd/server

Flags:

-s - Omit symbol table
-w - Omit DWARF debug info

Cross-Compilation

Build for different platforms:

# Linux AMD64
GOOS=linux GOARCH=amd64 go build -o bin/book-me-linux ./cmd/server

# macOS ARM64 (M1/M2)
GOOS=darwin GOARCH=arm64 go build -o bin/book-me-mac ./cmd/server

Dependencies

Core Dependencies

From go.mod:5-18:

Package	Purpose
`github.com/golang-jwt/jwt/v5`	JWT authentication
`github.com/lib/pq`	PostgreSQL driver
`github.com/joho/godotenv`	Environment variables
`github.com/go-playground/validator/v10`	Input validation
`github.com/wneessen/go-mail`	Email sending
`golang.org/x/oauth2`	OAuth2 client
`google.golang.org/api`	Google Calendar API
`golang.org/x/time`	Rate limiting
`github.com/hashicorp/go-retryablehttp`	Retry logic
`github.com/gorilla/sessions`	Session management

Installing Dependencies

All dependencies are defined in go.mod. Install with:

go mod download

Update to latest versions:

go get -u ./...
go mod tidy

Troubleshooting

Common Build Issues

Build fails with 'cmd/api not found'

The Makefile references the wrong path. Update Makefile:14:

- go build -o bin/book-me ./cmd/api
+ go build -o bin/book-me ./cmd/server

Database connection errors

Check:

PostgreSQL is running
DB_URL in .env is correct
Database exists and migrations are applied

Test connection:

psql "your-db-url"

SQLC generation fails

Ensure SQLC is installed:

go install github.com/sqlc-dev/sqlc/cmd/sqlc@latest

Verify sqlc.yaml configuration is correct.

Missing environment variables

The server will fail if required env vars are missing. Check internal/config/config.go for required fields.Copy and configure:

cp .env.example .env

Docker Build (Optional)

While not included in the repository, you can create a Dockerfile:

FROM golang:1.22-alpine AS builder
WORKDIR /app
COPY go.mod go.sum ./
RUN go mod download
COPY . .
RUN go build -ldflags="-s -w" -o bin/book-me ./cmd/server

FROM alpine:latest
RUN apk --no-cache add ca-certificates
WORKDIR /root/
COPY --from=builder /app/bin/book-me .
COPY --from=builder /app/.env .
EXPOSE 8080
CMD ["./book-me"]

Build and run:

docker build -t bookme:latest .
docker run -p 8080:8080 bookme:latest

Next Steps

Testing Guide - Learn about the test suite
Project Structure - Understand the codebase
Contributing - Submit your first PR

Developer Guide

Building the Project

Prerequisites

Quick Start

Build Commands

Available Make Targets

Detailed Build Process

Building the Binary

Running in Development

Standard Run

Hot Reload Development

Code Generation

SQLC - Type-Safe Database Queries

When to Regenerate

SQLC Workflow

Code Formatting

Format Go Code

Linting

Enabled Linters

Build Configuration

Binary Output

Application Entry Point

Environment-Specific Builds

Development Build

Production Build

Cross-Compilation

Dependencies

Core Dependencies

Installing Dependencies

Troubleshooting

Common Build Issues

Docker Build (Optional)

Next Steps

Build docs developers (and LLMs) love

Developer Guide

​Prerequisites

​Quick Start

​Build Commands

​Available Make Targets

​Detailed Build Process

​Building the Binary

​Running in Development

​Standard Run

​Hot Reload Development

​Code Generation

​SQLC - Type-Safe Database Queries

​When to Regenerate

​SQLC Workflow

​Code Formatting

​Format Go Code

​Linting

​Enabled Linters

​Build Configuration

​Binary Output

​Application Entry Point

​Environment-Specific Builds

​Development Build

​Production Build

​Cross-Compilation

​Dependencies

​Core Dependencies

​Installing Dependencies

​Troubleshooting

​Common Build Issues

​Docker Build (Optional)

​Next Steps

Build docs developers (and LLMs) love

Prerequisites

Quick Start

Build Commands

Available Make Targets

Detailed Build Process

Building the Binary

Running in Development

Standard Run

Hot Reload Development

Code Generation

SQLC - Type-Safe Database Queries

When to Regenerate

SQLC Workflow

Code Formatting

Format Go Code

Linting

Enabled Linters

Build Configuration

Binary Output

Application Entry Point

Environment-Specific Builds

Development Build

Production Build

Cross-Compilation

Dependencies

Core Dependencies

Installing Dependencies

Troubleshooting

Common Build Issues

Docker Build (Optional)

Next Steps