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

Workflow overview

The project uses a Git-flow workflow with automatic releases:

1. All development happens in the develop branch.
2. When code is ready for release, create a Pull Request from develop → main.
3. Merge the PR into main — this triggers an automatic release.
4. Drone builds the Docker image and pushes it to the Gitea Container Registry.

No manual Git tags are needed — merging into main is the release.

develop → PR → merge into main → Drone builds → Docker image pushed

Prerequisites

• Drone CI/CD runner must be configured and running at drone.jambotron.com.
• Gitea Container Registry must be enabled on the server.
• Repository secrets REGISTRY_USERNAME and REGISTRY_PASSWORD must be set in Drone.

Enabling Container Registry on Gitea server

Container Registry is a built-in feature of Gitea 1.17+. It is not configured through the web admin panel — it is enabled via the app.ini configuration file on the server.

1. Find app.ini on your server. The location depends on your installation method:

Installation	Path to app.ini
Docker (official image)	/data/gitea/conf/app.ini inside the container
System package (APT/YUM)	/etc/gitea/app.ini
Manual binary install	<working-dir>/custom/conf/app.ini

You can also find the path from Gitea web interface: Site Administration → Configuration Summary — look for CustomConf value.

2. Edit app.ini and add the [packages] section:

[packages]
ENABLED = true

If the [packages] section already exists, make sure ENABLED = true.

3. Restart Gitea to apply the changes:

# Docker
docker compose restart gitea

# System service
sudo systemctl restart gitea

4. Verify that the registry is working by visiting https://gitea.jambotron.com/user/packages — you should see a "Packages" tab.

Configuring Drone CI/CD

The repository uses Drone for CI/CD. The configuration file .drone.yml is already included in the repository. Drone is hosted at a separate domain: drone.jambotron.com.

1. Log in to Drone.

Open https://drone.jambotron.com and sign in with your Gitea account.

2. Activate the repository in Drone.

After logging in, find Liosha84/htop-web in the repository list and click Activate.

3. Configure Drone secrets.

In Drone, open the repository and go to Settings → Secrets. Add two secrets:

First secret:

• Name: REGISTRY_USERNAME
• Value: Liosha84 (your Gitea username)

Second secret:

• Name: REGISTRY_PASSWORD
• Value: paste the Access Token with write:package and read:package scopes.

Creating an Access Token for CI/CD

The CI/CD workflow cannot use your account password. You need a Personal Access Token with package permissions:

1. Log in to Gitea as Liosha84.
2. Go to Settings (your avatar → Settings).
3. In the left menu: Applications → Manage Access Tokens.
4. You'll see the section: "These tokens grant access to your account using the Gitea API."
5. Click Generate token.
6. Fill in:
   • Token name: ci-docker-push
   • Expiration: select No expiration (or set a date, but you'll need to update the secret later).
   • Scopes: check write:package and read:package.
7. Click Generate.
8. Copy the token — it will be shown only once! Save it securely.

Creating a release

1. Update CHANGELOG.md with changes for the new version in the develop branch.

2. Commit and push your changes to develop:

   git checkout develop
   git add -A
   git commit -m "Feature: new functionality"
   git push origin develop
   

3. Create a Pull Request from develop → main:

   Open https://gitea.jambotron.com/jambotron_gang/htop-web/compare/develop...main and click Create Pull Request.

4. Merge the PR into main.

5. Drone will automatically:

   • Build the Docker image using the multi-stage Dockerfile
   • Tag it with the short commit SHA (e.g., abc1234) and main-latest
   • Push both tags to the Gitea Container Registry

Docker image tags

Each merge into main produces two Docker image tags:

Tag	Example	Description
Commit SHA	gitea.jambotron.com/liosha84/htop-web:abc1234	Exact commit, use for reproducibility
Main latest	gitea.jambotron.com/liosha84/htop-web:main-latest	Most recent merge into main

Using a specific version in production

In docker-compose.yml, pin to a specific commit SHA:

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

Use main-latest for development/testing environments. For production, always use the commit SHA tag so you can roll back to a specific version.

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.