hatch-surf/docs/engineering/local-dev.md

Local Development

This is the day-to-day workflow for working on Hatch. If something here disagrees with what you actually observe, update this doc — the docs are a living artifact.

Prerequisites

• Go 1.25 or newer — go version should report 1.25+. Install from https://go.dev/doc/install or via your package manager.
• Docker (optional but recommended) — only required if you want to exercise the docker compose flow.
• curl — for smoke tests against the running server.
• sqlite3 CLI (optional) — for poking at the database file directly. Not required for the normal workflow.

Clone and Build

git clone https://github.com/elfoundation/hatch.git
cd hatch
go mod download

Run the Server

The fastest path is go run:

go run ./cmd/hatch
# hatch starting on :8080

In another terminal:

curl -fsS http://localhost:8080/healthz
# ok

The server reads its port from the PORT environment variable and defaults to :8080.

PORT=9090 go run ./cmd/hatch
# hatch starting on :9090

Run the Tests

go test ./...

This runs the full test suite, including the smoke test that boots the HTTP server in-process and hits /healthz. Add -v for verbose output, -race for the race detector.

go test ./... -v -race

Vet and Format

go vet ./...
gofmt -l .

CI runs go vet ./.... gofmt -l . lists any unformatted files (no output means everything is formatted). Run gofmt -w . to fix formatting in place.

Build a Static Binary

CGO_ENABLED=0 go build -ldflags="-s -w" -o bin/hatch ./cmd/hatch
ls -lh bin/hatch

The resulting binary is fully static, has no libc dependency, and runs on any Linux x86_64 with the same kernel.

Docker Compose

For the full local stack (Hatch + optional Caddy reverse proxy for TLS):

# Plain HTTP — Hatch only
docker compose up --build

# With Caddy (HTTPS, self-signed in dev)
docker compose --profile with-caddy up --build

The compose file reads .env for HATCH_HOSTNAME. Copy .env.example to .env and adjust:

cp .env.example .env
# Edit HATCH_HOSTNAME=localhost  (or your real domain)

Where Things Live

Path	Purpose
cmd/hatch/	Server entrypoint. main.go wires up http.ServeMux, main_test.go is the smoke test.
internal/handler/	HTTP handlers (Capture, Inspect, Mock). One file per route group.
internal/store/	Storage layer. schema.sql is the canonical DDL, sqlite_repo.go is the SQLite-backed implementation of the Repository interface.
docs/engineering/	Engineering standards and architecture docs.
docs/adrs/	Architecture Decision Records.
Dockerfile	Multi-stage build: golang:1.25-alpine → scratch with the static binary.
docker-compose.yml	Local stack: Hatch on :8080, optional Caddy sidecar for TLS.
.env.example	Documented environment variables.
hatch.db (gitignored)	SQLite database file. Created on first start in the working directory.

SQLite Tips

The database is a single file. By default it lives at ./hatch.db in the process working directory.

# Inspect the schema
sqlite3 hatch.db '.schema'

# List endpoints
sqlite3 hatch.db 'SELECT * FROM endpoints;'

# Reset (destructive)
rm hatch.db
# Schema is recreated on next start

For tests that need a clean database, use the :memory: SQLite database — see internal/store/sqlite_repo_test.go for the pattern. Do not point tests at the on-disk database file.

Common Tasks

Task	Command
Run the server	go run ./cmd/hatch
Run all tests	go test ./...
Run a single test	go test ./internal/handler -run TestCapture -v
Vet	go vet ./...
Format	gofmt -w .
Build a binary	CGO_ENABLED=0 go build -o bin/hatch ./cmd/hatch
Docker stack	docker compose up --build
Reset the database	rm hatch.db

Troubleshooting

go: command not found — Install Go 1.25+ and ensure $HOME/go/bin (or wherever go install puts binaries) is on your PATH.

bind: address already in use — Another process is on :8080. Either stop it or run with PORT=9090 go run ./cmd/hatch.

Tests fail with database is locked — A previous test process left a handle. Look for stray hatch processes (ps aux | grep hatch) and kill them. Tests should use :memory: databases and not share the on-disk file.

Docker build fails on go.sum — Run go mod tidy locally, commit go.sum, rebuild. The Dockerfile copies go.sum before go mod download for reproducible builds.

CGO_ENABLED warning during go build — The static-binary build sets CGO_ENABLED=0 explicitly. If you forget, the binary will dynamically link libc and break the "single static binary" promise.