Add README.md

2026-10-28 01:10:58 +01:00
parent 99185fa392
commit 3837466f2b
1 changed files with 150 additions and 0 deletions
@@ -0,0 +1,150 @@
+
+# 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
+
+```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
+```
+
+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:**
+
+```bash
+cd backend
+./gradlew clean build
+cd ..
+```
+
+**Windows PowerShell:**
+
+```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:
+
+```bash
+docker compose up -d --build
+```
+
+The default configuration publishes the application on port `8088`.
+
+Open:
+
+http://localhost:8088
+
+### 3. Check the container
+
+```bash
+docker compose ps
+docker compose logs -f htop-web
+```
+
+To stop the application:
+
+```bash
+docker compose down
+```
+
+## Project Structure
+
+```text
+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](docs/INSTALLATION.md)
+- [Configuration](docs/CONFIGURATION.md)
+- [Architecture](docs/ARCHITECTURE.md)
+- [Development](docs/DEVELOPMENT.md)
+- [Changelog](CHANGELOG.md)
+- [Contributing](CONTRIBUTING.md)
+
+## 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.