hnh-map/docs/development.md

Development

The recommended way to develop is Docker-first: run the app with make dev, and run tests, lint, and format with make test, make lint, and make fmt. All of these use Docker (see Makefile targets); you do not need Go or Node installed for the dev loop. Optionally, you can run backend or frontend locally without Docker (see Without Docker).

Local setup

Docker Compose (development)

docker compose -f docker-compose.dev.yml up

Or using the Makefile:

make dev

The dev Compose setup starts two services:

• backend — Go API on port 3080 (no frontend static serving in dev mode).
• frontend — Nuxt dev server on port 3000 with live-reload; requests to /map/api, /map/updates, /map/grids are proxied to the backend.

Use http://localhost:3000/ as the primary URL for UI development. Port 3080 is for API and backend endpoints; the root / may return 404 in dev mode — this is expected.

Testing navbar and profile: With no users in the database, log in as admin using the bootstrap password (e.g. HNHMAP_BOOTSTRAP_PASSWORD=admin in docker-compose.dev) to create the first admin user. You can then use that account to verify the navbar avatar and profile page. For Gravatar, use OAuth (e.g. Google) or set email later on the profile page once that feature is available.

Gravatar (avatar by email): Gravatar URLs are built on the frontend using the md5 package (client-side MD5 of the user's email). No backend endpoint is used; the frontend composable useGravatarUrl (see Phase 5+ of the navbar/avatar plan) will use this dependency.

Without Docker

You can run backend and frontend on the host if you have Go and Node installed.

Backend (Go)

From the repository root:

go build -o hnh-map ./cmd/hnh-map
./hnh-map -grids=./grids -port=8080

Or without building:

go run ./cmd/hnh-map -grids=./grids -port=8080

The server serves static files from the frontend/ directory (you need to build the frontend first, see below).

Frontend (Nuxt)

cd frontend-nuxt
npm install
npm run dev

In dev mode the app is available at root (e.g. http://localhost:3000/). The backend must be reachable; configure the proxy in nuxt.config.ts if needed (e.g. to http://localhost:8080).

Building the image and production Compose

docker build -t hnh-map .
docker compose -f docker-compose.prod.yml up -d

Or using the Makefile:

make build

In production the frontend is built into the image and served by the backend from the frontend/ directory; port 8080.

Makefile targets

All of test, lint, and fmt run inside Docker via docker-compose.tools.yml (backend and frontend tools containers with source mounted). No local Go or Node is required.

Target	Description
make dev	Start Docker Compose development environment
make build	Build production Docker image
make test	Run backend and frontend tests in Docker
make test-backend	Run Go tests in Docker only
make test-frontend	Run frontend (Vitest) tests in Docker only
make lint	Run Go (golangci-lint) and frontend (ESLint) linters in Docker
make fmt	Format all code (Go + frontend) in Docker
make generate-frontend	Build frontend static output into frontend/ (host)
make clean	Remove build artifacts

Running tests

From the repo root:

make test

This runs backend tests and frontend tests in Docker (see docker-compose.tools.yml). To run only one side: make test-backend or make test-frontend.

If you have Go and Node installed locally, you can instead run:

go test ./...
cd frontend-nuxt && npm test

See docs/testing.md for details on the test suite.