157 lines
4.8 KiB
Markdown
157 lines
4.8 KiB
Markdown
# 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.
|
|
|
|
<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
|
|
|
|
- **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.
|
|
|
|
## 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:**
|
|
|
|
```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.
|
|
|
|
### 2. Build and start the container
|
|
|
|
```bash
|
|
docker compose up -d --build
|
|
```
|
|
|
|
The default Compose configuration maps host port `8088` to container port `8080`.
|
|
|
|
Open [http://localhost:8088](http://localhost:8088).
|
|
|
|
### 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.
|