Skip to content
Public template

About

A lightweight, production-oriented Java 25 microservice template using Maven, Javalin, jOOQ, PostgreSQL, Flyway, Testcontainers, and Google Java Style. Designed as a clean GitHub template for small services without Spring or heavy framework abstractions.

Topics

Resources

Contributing

Security policy

Stars

2 stars

Watchers

0 watching

Forks

Repository files navigation

Lightweight Java Service Template

A GitHub template repository for small Java microservices that need a clean starting point without adopting a large application framework.

This is a template, not a framework. Click Use this template, initialize the service name/package, run the tests, and start replacing the tiny technical example with your service code.

Suggested GitHub description:

Lightweight Java 25 microservice template with Maven, Javalin, gRPC, jOOQ, PostgreSQL, Flyway, Testcontainers, and Google Java Style.

Suggested GitHub topics:

java, microservice-template, maven, javalin, grpc, protobuf, jooq, postgresql, flyway, testcontainers, google-java-format, no-spring

Quick Start

scripts/init-template.sh \
  --service-name orders-service \
  --package com.acme.orders \
  --group-id com.acme

make format
make test

Start local PostgreSQL and run the service:

make postgres-up
make run

Smoke-test HTTP:

make smoke

The service listens on:

  • HTTP: 8080
  • gRPC: 9090

What You Get

  • Java 25
  • Maven Wrapper
  • Javalin HTTP
  • direct grpc-java with protobuf code generation
  • Jackson JSON
  • jOOQ, HikariCP, PostgreSQL JDBC, and Flyway
  • SLF4J + Logback
  • JUnit 5, AssertJ, and Testcontainers
  • Google Java Format and Google Checkstyle
  • Dockerfile and Docker Compose PostgreSQL
  • GitHub Actions CI
  • AI-oriented repository guidance in AGENTS.md and .agents/

Structure

.
├── app/
│   ├── pom.xml
│   └── src/
├── docs/
├── scripts/
├── pom.xml
├── Makefile
├── docker-compose.yml
├── Dockerfile
└── README.md

Package boundaries:

com.example.service
├── bootstrap/
├── config/
├── http/
├── grpc/
├── application/
├── domain/
├── persistence/
└── observability/

Documentation

  • Template usage: initialization, local development, tests, routes, gRPC methods, repositories, migrations, and containers.
  • Architecture: philosophy, structure decision, package boundaries, dependency choices, and intentional omissions.
  • Agent guidance: rules for AI agents and maintainers working in this repository.

Common Commands

make help
make format
make grpc-generate
make test
make verify
make docker-build

Maven remains the source of truth:

./mvnw test
./mvnw clean verify

Template Philosophy

This repository is intentionally small. It favours explicit wiring, simple runtime behavior, low dependency count, fast tests, clear package boundaries, easy local development, and easy production hardening.

It avoids framework magic, premature modularisation, fake enterprise architecture, unnecessary annotations, unnecessary runtime reflection, and platform tooling that a small service may not actually use.

See docs/architecture.md for the full architecture decision record.

About

A lightweight, production-oriented Java 25 microservice template using Maven, Javalin, jOOQ, PostgreSQL, Flyway, Testcontainers, and Google Java Style. Designed as a clean GitHub template for small services without Spring or heavy framework abstractions.

Topics

Resources

Contributing

Security policy

Stars

2 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages