docs: improve project README
This commit is contained in:
@@ -1,64 +1,71 @@
|
||||
|
||||
# htop-web
|
||||
|
||||
**A self-hosted web-based system monitoring dashboard.**
|
||||
**A self-hosted, browser-based system monitoring dashboard powered by Angular and Spring Boot.**
|
||||
|
||||
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.
|
||||
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>
|
||||
|
||||
## 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.
|
||||
- **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
|
||||
|
||||
| Component | Technology |
|
||||
| Layer | Technology |
|
||||
|---|---|
|
||||
| Frontend | Angular 22, TypeScript, RxJS |
|
||||
| Backend | Java 21, Spring Boot, Spring WebFlux |
|
||||
| System information | OSHI |
|
||||
| Packaging | Gradle |
|
||||
| System inspection | OSHI |
|
||||
| Build | Gradle, npm |
|
||||
| Deployment | Docker, Docker Compose |
|
||||
|
||||
## Architecture
|
||||
|
||||
```text
|
||||
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
|
||||
Browser
|
||||
|
|
||||
v
|
||||
+----------------------+
|
||||
| htop-web container |
|
||||
| |
|
||||
| Spring Boot |
|
||||
| WebFlux |
|
||||
| | |
|
||||
| +-- REST API |
|
||||
| +-- System data |
|
||||
| +-- Process data |
|
||||
| |
|
||||
| Angular assets |
|
||||
+----------------------+
|
||||
```
|
||||
|
||||
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.
|
||||
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
|
||||
|
||||
From the repository root, run:
|
||||
Run from the repository root.
|
||||
|
||||
**Linux:**
|
||||
|
||||
@@ -76,30 +83,26 @@ cd backend
|
||||
cd ..
|
||||
```
|
||||
|
||||
The Gradle build installs frontend dependencies, builds the Angular application, packages the frontend assets and creates the Spring Boot JAR.
|
||||
The configured Gradle build builds the frontend and packages its production assets with the backend.
|
||||
|
||||
### 2. Start with Docker Compose
|
||||
|
||||
From the repository root:
|
||||
### 2. Build and start the container
|
||||
|
||||
```bash
|
||||
docker compose up -d --build
|
||||
```
|
||||
|
||||
The default configuration publishes the application on port `8088`.
|
||||
The default Compose configuration maps host port `8088` to container port `8080`.
|
||||
|
||||
Open:
|
||||
Open [http://localhost:8088](http://localhost:8088).
|
||||
|
||||
http://localhost:8088
|
||||
|
||||
### 3. Check the container
|
||||
### 3. Inspect logs
|
||||
|
||||
```bash
|
||||
docker compose ps
|
||||
docker compose logs -f htop-web
|
||||
```
|
||||
|
||||
To stop the application:
|
||||
### 4. Stop the application
|
||||
|
||||
```bash
|
||||
docker compose down
|
||||
@@ -111,20 +114,21 @@ docker compose down
|
||||
htop-web/
|
||||
├── backend/
|
||||
│ ├── src/main/java/com/htopweb/
|
||||
│ │ ├── system/
|
||||
│ │ └── ...
|
||||
│ ├── src/main/resources/
|
||||
│ ├── build.gradle
|
||||
│ └── gradlew
|
||||
│ └── build.gradle
|
||||
├── frontend/
|
||||
│ ├── src/app/
|
||||
│ │ ├── core/
|
||||
│ │ └── dashboard/
|
||||
│ ├── package.json
|
||||
│ └── angular.json
|
||||
├── docs/
|
||||
│ ├── INSTALLATION.md
|
||||
│ ├── CONFIGURATION.md
|
||||
│ ├── ARCHITECTURE.md
|
||||
│ └── DEVELOPMENT.md
|
||||
├── Dockerfile
|
||||
├── docker-compose.yml
|
||||
├── CONTRIBUTING.md
|
||||
├── CHANGELOG.md
|
||||
└── README.md
|
||||
```
|
||||
|
||||
@@ -137,14 +141,15 @@ htop-web/
|
||||
- [Changelog](CHANGELOG.md)
|
||||
- [Contributing](CONTRIBUTING.md)
|
||||
|
||||
## Monitoring Scope and Security
|
||||
## Security
|
||||
|
||||
System visibility depends on the operating system, runtime environment and permissions available to the application.
|
||||
System monitoring data can reveal sensitive information about the environment. Before exposing htop-web beyond a trusted network:
|
||||
|
||||
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.
|
||||
- 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. Check the repository's licensing requirements before reusing or redistributing this project.
|
||||
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.
|
||||
|
||||
Reference in New Issue
Block a user