htop-web/README.md

# htop-web

![htop-web](htop-web.gif)

**A self-hosted, browser-based system monitoring dashboard powered by Angular and Spring Boot.**

htop-web packages its Angular frontend and Spring Boot WebFlux backend into a single Docker container, providing a web interface for viewing system metrics and process information.

<p align="center">
  <img alt="Java 21" src="https://img.shields.io/badge/Java-21-orange?logo=openjdk&logoColor=white">
  <img alt="Spring Boot" src="https://img.shields.io/badge/Spring%20Boot-WebFlux-6DB33F?logo=springboot&logoColor=white">
  <img alt="Angular" src="https://img.shields.io/badge/Angular-22-DD0031?logo=angular&logoColor=white">
  <img alt="Docker" src="https://img.shields.io/badge/Docker-Compose-2496ED?logo=docker&logoColor=white">
</p>

## Demo

https://htop-web.jambotron.com/

## Features

- **System dashboard** — inspect system information through a browser.
- **CPU and memory metrics** — view resource measurements exposed by the backend.
- **Process information** — inspect available system process details.
- **Linux system information** — collect additional operating-system metrics.
- **Reactive backend** — built with Spring WebFlux.
- **Single-container architecture** — Angular production assets are served by Spring Boot.
- **Docker Compose deployment** — build, start, inspect and stop the application with standard Docker commands.

> **Monitoring scope:** metrics depend on the operating system, container runtime and granted permissions. Docker Desktop on Windows runs Linux containers in a virtualized environment; metrics from a container should not be assumed to represent the complete Windows host.

## Technology Stack

| Layer | Technology |
|---|---|
| Frontend | Angular 22, TypeScript, RxJS |
| Backend | Java 21, Spring Boot, Spring WebFlux |
| System inspection | OSHI |
| Build | Gradle, npm |
| Deployment | Docker, Docker Compose |

## Architecture

```text
                         Browser
                            |
                            v
                 +----------------------+
                 |  htop-web container |
                 |                      |
                 |  Spring Boot         |
                 |  WebFlux             |
                 |     |                |
                 |     +-- REST API     |
                 |     +-- System data  |
                 |     +-- Process data |
                 |                      |
                 |  Angular assets      |
                 +----------------------+
```

The Angular frontend is built for production and packaged into the Spring Boot application's static resources. Both parts are deployed together as one application container.

## Simple Scenario of using

```yaml
services:
  htop-web:
    image: gitea.jambotron.com/liosha84/htop-web:latest
    container_name: htop-web
    restart: unless-stopped
    pid: host
    read_only: true
    security_opt:
      - no-new-privileges:true
    tmpfs:
      - /tmp:noexec,nosuid,size=64m
    volumes:
      - /proc:/host/proc:ro
      - /sys:/host/sys:ro
      - /etc/hostname:/host/etc/hostname:ro
      - /etc/os-release:/host/etc/os-release:ro
      - /var:/host/var:ro
      - /home:/host/home:ro
      - /opt:/host/opt:ro
      - /tmp:/host/tmp:ro
      - /srv:/host/srv:ro
      - /usr:/host/usr:ro
    labels:
      caddy: htop-web.jambotron.com
      caddy.reverse_proxy: "{{upstreams 8080}}"
    networks:
      - jambotron-net

networks:
  jambotron-net:
    external: true
```

```bash
docker compose up -d
```


## Quick Start

### Requirements

- Docker Engine or Docker Desktop.
- Docker Compose.

No local Java or Node.js is required — the Dockerfile uses multi-stage build to compile everything inside Docker.

### 1. Build and start the container

From the repository root, run a single command:

```bash
docker compose up -d --build
```

The `--build` flag triggers the multi-stage Docker build that compiles both the Angular frontend and the Spring Boot backend inside Docker.

The default Compose configuration maps host port `8088` to container port `8080`.

Open [http://localhost:8088](http://localhost:8088).

### Alternative: Local Gradle build (requires Java 21 and Node.js)

If you need to build locally (for example, to run tests):

**Linux:**

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

**Windows PowerShell:**

```powershell
cd backend
.\gradlew.bat clean build
cd ..
```

The configured Gradle build builds the frontend and packages its production assets with the backend.

### 3. Inspect logs

```bash
docker compose ps
docker compose logs -f htop-web
```

### 4. Stop the application

```bash
docker compose down
```

## Project Structure

```text
htop-web/
├── backend/
│   ├── src/main/java/com/htopweb/
│   ├── src/main/resources/
│   └── build.gradle
├── frontend/
│   ├── src/app/
│   ├── package.json
│   └── angular.json
├── docs/
│   ├── INSTALLATION.md
│   ├── CONFIGURATION.md
│   ├── ARCHITECTURE.md
│   └── DEVELOPMENT.md
├── Dockerfile
├── docker-compose.yml
├── CONTRIBUTING.md
├── CHANGELOG.md
└── README.md
```

## Documentation

- [Installation](docs/INSTALLATION.md)
- [Configuration](docs/CONFIGURATION.md)
- [Architecture](docs/ARCHITECTURE.md)
- [Development](docs/DEVELOPMENT.md)
- [Changelog](CHANGELOG.md)
- [Contributing](CONTRIBUTING.md)

## Security

System monitoring data can reveal sensitive information about the environment. Before exposing htop-web beyond a trusted network:

- Put it behind appropriate authentication and access controls.
- Use HTTPS when accessed over an untrusted network.
- Grant the container only the permissions and host access it actually needs.
- Avoid publishing credentials, private keys or sensitive environment configuration.

## License

No license has been declared yet. Until a license is added, do not assume that the source code is available for unrestricted reuse or redistribution.