htop-web/README.md

htop-web

A self-hosted web-based system monitoring dashboard.

htop-web is a self-hosted application that combines an Angular frontend and a Spring Boot WebFlux backend in a single Docker container. It provides a browser-based interface for viewing system metrics and process information.

Features

• Web dashboard — monitor system information through a browser.
• CPU and memory metrics — inspect available system resource information.
• Process monitoring — view system processes and their reported details.
• Linux system details — collect additional operating-system information.
• Reactive backend — powered by Spring WebFlux.
• Single-container deployment — frontend assets are served by the Spring Boot application.
• Docker Compose support — straightforward deployment and restart management.

Technology Stack

Component	Technology
Frontend	Angular 22, TypeScript, RxJS
Backend	Java 21, Spring Boot, Spring WebFlux
System information	OSHI
Packaging	Gradle
Deployment	Docker, Docker Compose

Architecture

Browser
   |
   v
htop-web Docker container
   |
   +-- Spring Boot WebFlux
   |      |
   |      +-- REST controllers
   |      +-- System metrics services
   |      +-- Process information services
   |      +-- OSHI system inspection
   |
   +-- Angular production build
          |
          +-- Dashboard UI

The Angular production build is packaged into the Spring Boot application's static resources. The application and frontend therefore run together as one deployable service.

Requirements

• Java 21 for building the backend.
• Node.js and npm compatible with the frontend project.
• Docker Engine or Docker Desktop.
• Docker Compose.

Quick Start

1. Build the application

From the repository root, run:

Linux:

cd backend
./gradlew clean build
cd ..

Windows PowerShell:

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

The Gradle build installs frontend dependencies, builds the Angular application, packages the frontend assets and creates the Spring Boot JAR.

2. Start with Docker Compose

From the repository root:

docker compose up -d --build

The default configuration publishes the application on port 8088.

Open:

http://localhost:8088

3. Check the container

docker compose ps
docker compose logs -f htop-web

To stop the application:

docker compose down

Project Structure

htop-web/
├── backend/
│   ├── src/main/java/com/htopweb/
│   │   ├── system/
│   │   └── ...
│   ├── src/main/resources/
│   ├── build.gradle
│   └── gradlew
├── frontend/
│   ├── src/app/
│   │   ├── core/
│   │   └── dashboard/
│   ├── package.json
│   └── angular.json
├── docs/
├── Dockerfile
├── docker-compose.yml
└── README.md

Documentation

• Installation
• Configuration
• Architecture
• Development
• Changelog
• Contributing

Monitoring Scope and Security

System visibility depends on the operating system, runtime environment and permissions available to the application.

When running inside Docker, the application may report information about the container or the Linux environment hosting Docker rather than the physical host. Docker Desktop on Windows runs Linux containers inside a virtualized environment, so complete Windows host monitoring must not be assumed.

Do not expose the dashboard to untrusted networks without appropriate access controls and a secure deployment configuration.

License

No license has been declared yet. Check the repository's licensing requirements before reusing or redistributing this project.