Liosha84andJunie
f3e095dafc
- Add .gitea/workflows/docker.yml: builds and pushes Docker image on Git tags with semantic versioning (v0.1.0 → tags 0.1.0, 0.1, latest) - Add .dockerignore to optimize Docker build context - Document release process in docs/DEVELOPMENT.md - Update CHANGELOG.md with v0.1.0 release and Unreleased CI/CD entry Required Gitea secrets: REGISTRY_USERNAME, REGISTRY_PASSWORD Co-authored-by: Junie <junie@jetbrains.com>
154 lines
3.9 KiB
Markdown
154 lines
3.9 KiB
Markdown
# 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
|
|
|
|
### 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:
|
|
|
|
```bash
|
|
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:
|
|
|
|
```bash
|
|
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:
|
|
|
|
```yaml
|
|
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.
|