htop-web/README.md

htop-web

# **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.

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

                         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.

Quick Start

Requirements

• Java 21 and a compatible Node.js/npm installation for local builds.
• Docker Engine or Docker Desktop.
• Docker Compose.

1. Build the application

Run from the repository root.

Linux:

cd backend
./gradlew clean build
cd ..

Windows PowerShell:

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

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

2. Build and start the container

docker compose up -d --build

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

Open http://localhost:8088.

3. Inspect logs

docker compose ps
docker compose logs -f htop-web

4. Stop the application

docker compose down

Project Structure

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
• Configuration
• Architecture
• Development
• Changelog
• Contributing

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.