spring-template

Spring Boot service template for a solo project that ships to one VPS. Clone, rename, push: CI publishes a versioned image, the server pulls it and rolls the replicas, Grafana shows the release. Local run needs no configuration.

make run              # starts Postgres from compose.yml, runs the app on :8080
make observability-up # Prometheus + Grafana (http://localhost:3000) + Alloy scraping the app
make test             # unit tests, no Docker
make itest            # integration tests, Testcontainers
make help             # everything else

make run uses the defaults in .env.example; create .env only to override them. Port 5432 taken? DB_PORT=15433 make run.

Endpoints: /version, /actuator/health, /actuator/prometheus, /swagger-ui.html.

One VPS (Hetzner CX or CAX both work: images are amd64 + arm64), Docker installed, ports 80/443 open, a domain.

On the VPS:

git clone https://github.com/<owner>/<repo>.git && cd <repo>
make prod-init                 # writes deploy/.env.prod: generated DB password, image name from the git remote
$EDITOR deploy/.env.prod       # DOMAIN, ACME_EMAIL, optional Grafana Cloud block
make prod-up                   # validates the env, starts Caddy + 2 app replicas + Postgres + Watchtower + backup

Then push to main. Nothing on the VPS is touched again.

git push main ─► ci: build+tests ‖ gitleaks+trivy+zizmor ─► image (amd64+arm64) ─► tag vX.Y.Z + Release
                                                                     │
                                          Watchtower polls GHCR ◄────┘   every 60 s
                                                  │
                     stop replica 1 (graceful) ─► start new ─► replica 2 ─► /version shows the new revision

Watchtower waits for each new replica's health check before stopping the next one, and Caddy re-resolves the app service name every 5 s and retries only connection-level failures, so a rolling restart is invisible to clients. Postgres and the management port are never reachable from the internet.

Rollback on the VPS: make prod-rollback TAG=1.4.1 (every GitHub Release lists its tag and this command). Details, first-time host setup, backups and the migration rule: docs/deployment.md.

Commit subjects follow Conventional Commits; make setup (run automatically by make run/test/build) installs a hook that rejects anything else, and CI checks again.

make release-name prints the version the next push would produce. Image tags: latest, X.Y.Z, X.Y, sha-<short>. The Release notes list every commit since the previous tag.

One dashboard, deploy/grafana/dashboards/app-overview.json, renders locally and in Grafana Cloud: running version and deploy markers (from app_build_info), HTTP rate/errors/latency, JVM, Hikari, log levels, circuit breakers. Edit it in the local Grafana, make grafana-pull, commit; CI pushes it to Grafana Cloud. Alerts (service down, 5xx > 5 %, DB connections pending, heap > 90 %) are pushed only when the Telegram secrets exist. docs/observability.md.

• src/test/java/**/unit/** and everything outside integration/: no Docker, classes run concurrently.
• src/test/java/**/integration/**: extend AbstractIntegrationTest; each Gradle fork boots its own context and its own Postgres container, so forks never share a database.
• Test data with Instancio (support.Fixtures); architecture rules in ArchitectureTest; DashboardJsonTest keeps the Grafana JSON honest; scripts/tests/*.test.sh cover the bash tooling (make test-scripts).

make rename PKG=com.acme.shop APP=shop   # moves the package, renames the app, one reviewable diff
make build

Then add the first Liquibase changeset under src/main/resources/db/changelog/changes/ and go.

MIT — see LICENSE.