htop-web/docs/DEVELOPMENT.md

Development

Prerequisites

• Java 21
• Node.js and npm compatible with frontend/package.json
• Docker Engine and Docker Compose for container testing

Build and test

Option 1: Gradle build (requires Java 21 and Node.js)

From the repository root:

cd backend
./gradlew clean build

This invokes the configured Gradle build, including frontend build tasks.

Option 2: Docker multi-stage build (requires only Docker)

Build the entire application inside Docker — no local Java or Node.js required:

docker build -t htop-web .

This uses a multi-stage Dockerfile with three stages:

1. Frontend — builds Angular with Node.js 22 Alpine
2. Builder — compiles the backend with Gradle and Java 21 JDK
3. Runtime — packages only the JAR and Java 21 JRE (~200 MB final image)

The Docker build is fully reproducible and does not depend on tools installed on the host machine.

Frontend development

Frontend source code is located in frontend/.

Install dependencies using the lockfile:

cd frontend
npm ci

Run the frontend development server using the project's configured npm scripts:

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

With Docker Compose (recommended)

From the repository root:

docker compose up -d --build
docker compose logs -f htop-web

The --build flag triggers the multi-stage Docker build automatically.

With Docker only

If you built the image manually:

docker run -d \
  --name htop-web \
  --pid host \
  --read-only \
  --security-opt no-new-privileges:true \
  --tmpfs /tmp:noexec,nosuid,size=64m \
  -v /proc:/host/proc:ro \
  -v /sys:/host/sys:ro \
  -v /etc/hostname:/host/etc/hostname:ro \
  -v /etc/os-release:/host/etc/os-release:ro \
  -v /var:/host/var:ro \
  -v /home:/host/home:ro \
  -v /opt:/host/opt:ro \
  -v /tmp:/host/tmp:ro \
  -v /srv:/host/srv:ro \
  -v /usr:/host/usr:ro \
  -p 8080:8080 \
  htop-web

Release process

Prerequisites

• Gitea Actions runner must be configured and running.
• Repository secrets REGISTRY_USERNAME and REGISTRY_PASSWORD must be set in Settings → Secrets of the Gitea repository. These credentials are used to authenticate with the Gitea Container Registry.

Creating a release

1. Update CHANGELOG.md with changes for the new version.

2. Commit and push your changes:

   git add -A
   git commit -m "Prepare release v0.2.0"
   git push origin master
   

3. Create and push a Git tag with Semantic Versioning:

   git tag -a v0.2.0 -m "Release v0.2.0: new features and fixes"
   git push origin v0.2.0
   

4. Gitea Actions will automatically:

   • Build the Docker image using the multi-stage Dockerfile
   • Tag it with the version (0.2.0), minor version (0.2), and latest
   • Push all three tags to the Gitea Container Registry

Docker image tags

Each release produces three Docker image tags:

Tag	Example	Description
Full version	gitea.jambotron.com/liosha84/htop-web:0.2.0	Exact version, use in production
Minor version	gitea.jambotron.com/liosha84/htop-web:0.2	Latest patch of 0.2.x
Latest	gitea.jambotron.com/liosha84/htop-web:latest	Most recent stable release

Using a specific version in production

In docker-compose.yml, always pin to a specific version:

services:
  htop-web:
    image: gitea.jambotron.com/liosha84/htop-web:0.2.0

Avoid using :latest in production — it makes rollbacks impossible and breaks reproducibility.

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.