# 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](#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](#without-docker)).

## Local setup

### Docker Compose (development)

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

Or using the Makefile:

```bash
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/](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:

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

Or without building:

```bash
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)

```bash
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

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

Or using the Makefile:

```bash
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:

```bash
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:

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

See [docs/testing.md](testing.md) for details on the test suite.