Library API in Spring Boot: N-tier, JPA and Flyway, Docker, CI with the conformance suite

Author: Edrzapi

.dockerignore

@@ -0,0 +1,13 @@
+.git/
+.github/
+.idea/
+.vscode/
+target/
+*.db
+*.db-journal
+*.log
+*.iml
+README.md
+docker-compose.yml
+Dockerfile
+.dockerignore

.gitattributes

@@ -0,0 +1,5 @@
+# Shell scripts must keep LF line endings to run on Linux and macOS; Windows scripts keep CRLF.
+* text=auto
+mvnw text eol=lf
+*.sh text eol=lf
+*.cmd text eol=crlf

.github/workflows/ci.yml

@@ -0,0 +1,110 @@
+# CI for the Library API (Spring Boot).
+# On every push and pull request: build and run the unit tests, then start the API
+# in test mode and run the contract's conformance suite against it, once with
+# SQLite and once with PostgreSQL 17.
+
+# The name shown in the Actions tab.
+name: CI
+
+# What starts the workflow: any push and any pull request.
+on:
+  push:
+  pull_request:
+
+# The jobs to run. Each job gets a fresh Ubuntu machine.
+jobs:
+  unit-tests:
+    # The machine the job runs on.
+    runs-on: ubuntu-latest
+
+    # The steps run in order; the first failure stops the job.
+    steps:
+      # "uses" runs a published action. This one checks out this repository.
+      - uses: actions/checkout@v5
+
+      - name: Set up Java 21
+        uses: actions/setup-java@v5
+        # "with" passes inputs to the action.
+        with:
+          distribution: temurin
+          java-version: "21"
+          # Keep downloaded Maven dependencies between runs.
+          cache: maven
+
+      - name: Build and run the unit tests
+        # "run" runs shell commands. chmod in case mvnw lost its execute bit on Windows.
+        run: |
+          chmod +x mvnw
+          ./mvnw -B verify
+
+  conformance:
+    # Only start when the unit tests have passed.
+    needs: unit-tests
+    runs-on: ubuntu-latest
+
+    # Run this job once for each value in the list.
+    strategy:
+      # Let the other database finish even if one fails.
+      fail-fast: false
+      matrix:
+        database: [sqlite, postgresql]
+
+    # Containers that run next to the job. The SQLite run ignores this one.
+    services:
+      postgres:
+        image: postgres:17
+        env:
+          POSTGRES_USER: library
+          POSTGRES_PASSWORD: library
+          POSTGRES_DB: library
+        ports:
+          - 5432:5432
+        # Wait until PostgreSQL accepts connections before the steps start.
+        options: >-
+          --health-cmd "pg_isready -U library -d library"
+          --health-interval 5s --health-timeout 3s --health-retries 20
+
+    # Environment variables for every step. TEST_MODE=1 turns on POST /test/reset and X-Today.
+    env:
+      PORT: "8000"
+      TEST_MODE: "1"
+      DATABASE_URL: ${{ matrix.database == 'postgresql' && 'postgresql://library:library@localhost:5432/library' || 'sqlite:///library.db' }}
+
+    steps:
+      - uses: actions/checkout@v5
+
+      - name: Check out the contract
+        uses: actions/checkout@v5
+        with:
+          repository: devfoundry-training/Library_API_Contract
+          path: contract
+
+      - name: Set up Java 21
+        uses: actions/setup-java@v5
+        with:
+          distribution: temurin
+          java-version: "21"
+          cache: maven
+
+      - name: Set up Python for the conformance suite
+        uses: actions/setup-python@v6
+        with:
+          python-version: "3.13"
+
+      - name: Build the jar
+        run: |
+          chmod +x mvnw
+          ./mvnw -B -q package -DskipTests
+
+      - name: Start the API
+        run: |
+          nohup java -jar target/library-api.jar > app.log 2>&1 &
+          for _ in $(seq 1 90); do curl -fs http://localhost:8000/health && break; sleep 1; done
+
+      - name: Conformance suite (${{ matrix.database }})
+        run: python contract/conformance/run.py --base-url http://localhost:8000
+
+      - name: Server log
+        # Only when an earlier step failed.
+        if: failure()
+        run: cat app.log

.gitignore

@@ -0,0 +1,29 @@
+# Maven
+target/
+.mvn/wrapper/maven-wrapper.jar
+
+# Local SQLite databases
+*.db
+*.db-journal
+*.db-wal
+*.db-shm
+
+# Logs
+*.log
+
+# IDEs
+.idea/
+*.iml
+.vscode/
+.classpath
+.project
+.settings/
+.factorypath
+bin/
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Python virtual environment (for the conformance suite)
+.venv/

.mvn/wrapper/maven-wrapper.properties

@@ -0,0 +1,3 @@
+wrapperVersion=3.3.4
+distributionType=only-script
+distributionUrl=https://repo.maven.apache.org/maven2/org/apache/maven/apache-maven/3.9.16/apache-maven-3.9.16-bin.zip

Dockerfile

@@ -0,0 +1,35 @@
+# Library API (Spring Boot): build the jar with the Maven wrapper, then run it on a JRE as a non-root user.
+#   docker build -t library-api-springboot .
+#   docker run -p 8000:8000 library-api-springboot
+
+# ---- build stage ----
+FROM eclipse-temurin:21.0.12.1_1-jdk-noble AS build
+WORKDIR /src
+
+# Dependencies first, so a code change does not download them again.
+COPY .mvn/ .mvn/
+COPY mvnw pom.xml ./
+RUN chmod +x mvnw && ./mvnw -B -q dependency:go-offline
+
+COPY src/ src/
+RUN ./mvnw -B -q package -DskipTests
+
+# ---- runtime stage ----
+FROM eclipse-temurin:21.0.12.1_1-jre-alpine
+
+# Time zone data for Europe/London, and a user without root rights.
+RUN apk add --no-cache tzdata \
+    && addgroup -S library \
+    && adduser -S -G library -h /app library
+
+WORKDIR /app
+COPY --from=build /src/target/library-api.jar app.jar
+RUN chown library:library /app
+
+USER library
+ENV PORT=8000 \
+    TZ=Europe/London
+EXPOSE 8000
+
+# Flyway runs the migrations on start-up, then the sample data is loaded if the database is empty.
+ENTRYPOINT ["java", "-jar", "/app/app.jar"]