Generate a service

Spring Boot with build, contract, telemetry, image, manifests and CI, as the guides do it.

Project
Lowercase words joined by hyphens, such as orders or order-history.
The Gradle group: lowercase segments joined by dots.
Morepackage com.example.demo
The base Java package. Defaults to the group followed by the name without hyphens.
One line for the README and the API contract.
Options
Architecture
How the code inside each capability is arranged.
Database
PostgreSQL with migrations in a Job and two database roles. Default none.
Login
OpenID Connect: the service accepts only tokens for its API; the frontend, if any, logs users in.
Frontend
A Next.js frontend in frontends/web, with its own image and Deployment.
From a terminal
curl https://start.pyahu.io/starter.zip -o demo.zip

Baseline v0.1-b2: Java 25.0.5+8, Spring Boot 4.1.2.

demo49 files
# demo

Demo service generated by the Pyahu Initializer

Generated by the [Pyahu Initializer](https://initializer.pyahu.io/) on baseline v0.1-b2: Java 25 and
Spring Boot 4.1.2. Every file follows one of the [guides](https://initializer.pyahu.io/guides/); the comments
name the guide and step behind each choice. The guides ask for more than a starter can decide for you:
`CHECKLIST.md` lists what is left to do.

## Run it

```sh
./gradlew bootRun                # starts the containers of compose.yml, then the service
curl localhost:8080/ping         # {"message":"pong"}
```

Traces, metrics and logs land in Grafana on http://localhost:3000 (admin/admin).

## Build it

```sh
./gradlew build                  # compile with Error Prone and NullAway, tests, Spotless, SBOM
docker build -t demo .       # image with layers and an AOT cache, running as user 10001
kustomize build deploy/overlays/dev
```

`./gradlew spotlessApply` formats the code. CI does all of the above on every push
(`.github/workflows/ci.yml`), then checks the rendered dev and prod manifests with strict Kubernetes 1.36 and 1.37
schemas, kube-linter, Trivy (HIGH/CRITICAL misconfigurations) and Pluto for deprecated or removed APIs.
It scans the exact built backend images for fixable HIGH/CRITICAL vulnerabilities
before smoke tests.
Renovate keeps the versions current (`renovate.json`).

## Where things are

| Path | What |
| ---- | ---- |
| `src/main/openapi/api.yaml` | The REST contract. The build generates the interfaces the controllers implement. |
| `src/main/java/.../ping/domain/` | The rules, plain Java. |
| `src/main/java/.../ping/application/port/` | What the capability offers and needs. |
| `src/main/java/.../ping/application/service/` | The use cases behind the ports. |
| `src/main/java/.../ping/adapter/` | The web and, later, the database. |
| `src/main/resources/application.yaml` | Every setting, with local defaults the Deployment overrides. |
| `deploy/` | Kustomize: a base, a `dev` and a `prod` overlay. |
| `compose.yml` | The local loop: Grafana with OpenTelemetry. |
| `CHECKLIST.md` | What to review before production, with the step that explains each item. |

The architecture is Hexagonal: [guide](https://initializer.pyahu.io/guides/architecture/#arch-hexagonal).

## Deploy it

Set the real image references, database and identity provider addresses in the overlay first. Production requires
published image digests. Select the target context explicitly; this helper never changes your current context.

```sh
bash deploy/apply.sh --context YOUR_CONTEXT dev prepare
# Provision the Secrets below in the namespace just created, using your secret store.
bash deploy/apply.sh --context YOUR_CONTEXT dev release
```

Use `prod` for the production overlay. `prepare` applies the Namespace, ServiceAccounts, generated ConfigMaps and
NetworkPolicies. `release` applies those prerequisites again, checks required Secret keys, then applies the application and waits for its rollout.
A failed migration stops the release before a new Deployment is applied.

The helper renders the overlay once, so the migration and application use the same ConfigMap hashes. A plain apply
of the entire overlay does not wait for a successful migration. When using GitOps, configure the same prerequisite,
migration and application ordering in the controller instead of also running this helper. Retire unused generated
ConfigMaps only after no running workload references them.