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:

```bash
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:

```bash
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:

```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

### With Docker Compose (recommended)

From the repository root:

```bash
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:

```bash
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:

```ini
[packages]
ENABLED = true
```

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

**3. Restart Gitea** to apply the changes:

```bash
# 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`:

   ```bash
   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:

```yaml
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.