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.

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

                         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

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

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:

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.

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

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

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.

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.