# Development

## Prerequisites

- Java 21
- Node.js and npm compatible with `frontend/package.json`
- Docker Engine and Docker Compose for container testing

## Build and test

### Option 1: Gradle build (requires Java 21 and Node.js)

From the repository root:

```bash
cd backend
./gradlew clean build
```

This invokes the configured Gradle build, including frontend build tasks.

### Option 2: Docker multi-stage build (requires only Docker)

Build the entire application inside Docker — no local Java or Node.js required:

```bash
docker build -t htop-web .
```

This uses a multi-stage Dockerfile with three stages:
1. **Frontend** — builds Angular with Node.js 22 Alpine
2. **Builder** — compiles the backend with Gradle and Java 21 JDK
3. **Runtime** — packages only the JAR and Java 21 JRE (~200 MB final image)

The Docker build is fully reproducible and does not depend on tools installed on the host machine.

## Frontend development

Frontend source code is located in `frontend/`.

Install dependencies using the lockfile:

```bash
cd frontend
npm ci
```

Run the frontend development server using the project's configured npm scripts:

```bash
npm start
```

If the project does not define a `start` script, inspect `frontend/package.json` and use its available script, such as `npm run`.

## Run the container

### With Docker Compose (recommended)

From the repository root:

```bash
docker compose up -d --build
docker compose logs -f htop-web
```

The `--build` flag triggers the multi-stage Docker build automatically.

### With Docker only

If you built the image manually:

```bash
docker run -d \
  --name htop-web \
  --pid host \
  --read-only \
  --security-opt no-new-privileges:true \
  --tmpfs /tmp:noexec,nosuid,size=64m \
  -v /proc:/host/proc:ro \
  -v /sys:/host/sys:ro \
  -v /etc/hostname:/host/etc/hostname:ro \
  -v /etc/os-release:/host/etc/os-release:ro \
  -v /var:/host/var:ro \
  -v /home:/host/home:ro \
  -v /opt:/host/opt:ro \
  -v /tmp:/host/tmp:ro \
  -v /srv:/host/srv:ro \
  -v /usr:/host/usr:ro \
  -p 8080:8080 \
  htop-web
```

## Contribution guidelines

- Keep changes focused and reviewable.
- Do not commit generated build output or dependency directories.
- Do not commit credentials, private keys, or local environment files.
- Update documentation when build or runtime behavior changes.
- Run the build before submitting changes.