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. Local run needs no configuration.

make run              # starts Postgres from compose.yml, runs the app on :8080
make test             # unit tests, no Docker
make itest            # integration tests, Testcontainers
make bricks           # optional pieces: observability, backup, minio → make add BRICK=<name>
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
make prod-up                   # validates the env, starts Caddy + 2 app replicas + Postgres + Watchtower (+ enabled bricks)

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

Optional infrastructure lives in bricks/<name>/ and is inert until added:

make add wires compose, env, Java, make targets and a Claude skill from that one folder; make remove takes it all out. Each brick's README is its runbook; bricks/README.md is the contract for writing one.

• services/app/src/test/java/**/unit/** and everything outside integration/: no Docker, classes run concurrently.
• services/app/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; scripts/tests/*.test.sh cover the bash tooling (make test-scripts); the observability brick ships DashboardJsonTest.

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 services/app/src/main/resources/db/changelog/changes/ and go.

MIT — see LICENSE.