Arnike/hnh-map
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Enhance development workflow with Docker integration

Browse Source 
- 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.
This commit is contained in:
Nikolay Tatarinov
2026-03-04 11:39:27 +03:00
parent adfdfd01c4
commit a3a4c0e896
8 changed files with 120 additions and 84 deletions
Download Patch File Download Diff File Expand all files Collapse all files

86
docs/development.md
View File

@@ -1,34 +1,9 @@
# 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
### 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`).
### Docker Compose (development)
```bash
@@ -53,6 +28,37 @@ Port `3080` is for API and backend endpoints; the root `/` may return `404` in d
**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
@@ -70,33 +76,35 @@ In production the frontend is built into the image and served by the backend fro
## 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 Go tests (`go test ./...`) |
| `make lint` | Run Go and frontend linters |
| `make fmt` | Format all code (Go + frontend) |
| `make generate-frontend` | Build frontend static output into `frontend/` |
| `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
```
Or directly:
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 ./...
```
For frontend tests (if configured):
```bash
cd frontend-nuxt
npm test
cd frontend-nuxt && npm test
```
See [docs/testing.md](testing.md) for details on the test suite.