diff --git a/CHANGELOG.md b/CHANGELOG.md new file mode 100644 index 0000000..e7df7c4 --- /dev/null +++ b/CHANGELOG.md @@ -0,0 +1,9 @@ +# Changelog + +All notable project changes should be documented here. + +This project has not yet established a versioned changelog. Add entries as releases are published. + +## Unreleased + +- Documentation structure established. diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000..10d57f3 --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,34 @@ +# Contributing + +Thank you for your interest in improving htop-web. + +## Before making changes + +1. Review the README and relevant documentation. +2. Check the existing implementation before introducing new dependencies or changing behavior. +3. Keep changes focused on a clear issue or improvement. + +## Development workflow + +1. Create a branch for your change. +2. Implement and test the change. +3. Run the backend Gradle build from `backend/`: + + ```bash + ./gradlew clean build + ``` + +4. Review the Git diff and ensure generated files, credentials, and local configuration are not included. +5. Update documentation when necessary. +6. Submit your changes with a clear description of the problem and solution. + +## Code quality + +- Follow the conventions already used in the relevant module. +- Avoid unrelated refactoring. +- Do not claim support for monitoring capabilities that have not been tested in the target environment. +- Never commit passwords, tokens, private keys, or production secrets. + +## Reporting issues + +Include the steps to reproduce the issue, expected behavior, actual behavior, relevant logs, and environment details. Remove sensitive information from logs before sharing them. diff --git a/docs/ARCHITECTURE.md b/docs/ARCHITECTURE.md new file mode 100644 index 0000000..b35e213 --- /dev/null +++ b/docs/ARCHITECTURE.md @@ -0,0 +1,44 @@ +# Architecture + +## Overview + +htop-web is designed as a single deployable application containing an Angular frontend and a Spring Boot backend. + +```text +Web browser + | + | HTTP + v +Spring Boot application + | + +-- Angular production assets + | + +-- WebFlux REST controllers + | + +-- System information services + | + +-- OSHI + +-- Operating-system information +``` + +## Frontend + +The frontend is implemented with Angular and TypeScript. Its source code is located in `frontend/src/`. + +The production build is generated during the Gradle build and copied into the backend's static resources. + +## Backend + +The backend uses Java, Spring Boot and Spring WebFlux. Backend source code is located in `backend/src/main/java/com/htopweb/`. + +Controllers expose system information to the frontend, while service classes collect and prepare the relevant data. + +## System information + +OSHI is used to obtain operating-system and hardware information. The data available depends on the runtime environment and permissions. + +## Packaging + +The Gradle build combines the frontend production assets with the Spring Boot application. Docker packages the resulting JAR into a single application container. + +See the root `Dockerfile` and `docker-compose.yml` for the current container setup. diff --git a/docs/CONFIGURATION.md b/docs/CONFIGURATION.md new file mode 100644 index 0000000..979cb3b --- /dev/null +++ b/docs/CONFIGURATION.md @@ -0,0 +1,28 @@ +# Configuration + +## Docker Compose + +The root `docker-compose.yml` defines the application container. + +Default port mapping: + +- Host: `8088` +- Container: `8080` + +Change the port mapping in `docker-compose.yml` if host port `8088` is already in use. + +## Application settings + +The Spring Boot configuration is maintained in: + +`backend/src/main/resources/application.yaml` + +Review the actual configuration file before changing application properties. This document intentionally does not assume environment variables or settings that may not exist in the current implementation. + +## Container permissions and monitoring scope + +System metrics available to the application depend on the operating system, container runtime, mounted filesystems, and granted permissions. + +A container does not automatically have complete visibility into its host. Docker Desktop on Windows runs Linux containers in a virtualized Linux environment, so reported metrics may describe that environment rather than Windows itself. + +Do not expose the monitoring interface to untrusted networks without appropriate access controls and network security. diff --git a/docs/DEVELOPMENT.md b/docs/DEVELOPMENT.md new file mode 100644 index 0000000..5cfcf0a --- /dev/null +++ b/docs/DEVELOPMENT.md @@ -0,0 +1,54 @@ +# Development + +## Prerequisites + +- Java 21 +- Node.js and npm compatible with `frontend/package.json` +- Docker Engine and Docker Compose for container testing + +## Build and test + +From the repository root: + +```bash +cd backend +./gradlew clean build +``` + +This invokes the configured Gradle build, including frontend build tasks. + +## Frontend development + +Frontend source code is located in `frontend/`. + +Install dependencies using the lockfile: + +```bash +cd frontend +npm ci +``` + +Run the frontend development server using the project's configured npm scripts: + +```bash +npm start +``` + +If the project does not define a `start` script, inspect `frontend/package.json` and use its available script, such as `npm run`. + +## Run the container + +From the repository root, after a successful build: + +```bash +docker compose up -d --build +docker compose logs -f htop-web +``` + +## Contribution guidelines + +- Keep changes focused and reviewable. +- Do not commit generated build output or dependency directories. +- Do not commit credentials, private keys, or local environment files. +- Update documentation when build or runtime behavior changes. +- Run the build before submitting changes. diff --git a/docs/INSTALLATION.md b/docs/INSTALLATION.md new file mode 100644 index 0000000..1e4d044 --- /dev/null +++ b/docs/INSTALLATION.md @@ -0,0 +1,42 @@ +# Installation + +## Requirements + +- Docker Engine +- Docker Compose +- Java 21 and Node.js/npm if building the application locally + +## Build the application + +From the repository root: + +```bash +cd backend +./gradlew clean build +cd .. +``` + +The Gradle build also builds the Angular frontend and packages its production assets into the Spring Boot application. + +## Start with Docker Compose + +```bash +docker compose up -d --build +``` + +The default Compose configuration maps host port `8088` to container port `8080`. + +Open http://localhost:8088 in your browser. + +## Check status and logs + +```bash +docker compose ps +docker compose logs -f htop-web +``` + +## Stop the application + +```bash +docker compose down +```