Nikolay Tatarinov
a3a4c0e896
- Updated CONTRIBUTING.md to clarify the use of Makefile targets for running tasks inside Docker, eliminating the need for local Go or Node installations. - Introduced docker-compose.tools.yml for backend and frontend tools, allowing for streamlined testing, linting, and formatting. - Created Dockerfile.tools to set up a Go environment with necessary tools for testing and linting. - Modified Makefile to include separate targets for backend and frontend tests, improving clarity and usability. - Updated documentation in development.md and testing.md to reflect the new Docker-based workflow for running tests and development tasks.
111 lines
3.8 KiB
Markdown
111 lines
3.8 KiB
Markdown
# 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.
|