Adrien
d8bcdce879
commit 0d624137c2557c6eeb87020749e4977b821c2b5c Author: Adrien <adrien.cesaro@proton.me> Date: Thu Apr 9 11:55:22 2026 +0200 backend native image setup
48 lines
1.8 KiB
Markdown
48 lines
1.8 KiB
Markdown
# Build Contract: Native Image
|
|
|
|
**Branch**: `005-native-image-deployment` | **Date**: 2026-04-07
|
|
|
|
## Overview
|
|
|
|
This contract defines what the native build produces and how consumers (developers, CI, docker-compose)
|
|
interact with it. The REST API contract is **unchanged** — all existing endpoints remain identical.
|
|
|
|
## Build Inputs
|
|
|
|
| Input | Required | Description |
|
|
|-------|----------|-------------|
|
|
| GraalVM JDK 25 | Yes (native profile only) | `JAVA_HOME` must point to GraalVM 25 |
|
|
| `DOCKER_HOST` / Docker daemon | Optional | Required for `jib:dockerBuild`; not needed for `jib:build` |
|
|
| `jib.to.image` Maven property | Optional | Override target image name; defaults to `ai-teacher-backend` |
|
|
|
|
## Build Outputs
|
|
|
|
| Profile | Command | Output |
|
|
|---------|---------|--------|
|
|
| Default (JVM) | `mvn package` | `target/ai-teacher-backend-*.jar` |
|
|
| Native | `mvn -Pnative package` | `target/ai-teacher-backend` (native executable) |
|
|
| Native + Docker | `mvn -Pnative package jib:dockerBuild` | Local Docker image `ai-teacher-backend:latest` |
|
|
| Native + Registry | `mvn -Pnative package jib:build` | Remote Docker image (configured via properties) |
|
|
|
|
## Docker Image Contract
|
|
|
|
| Property | Value |
|
|
|----------|-------|
|
|
| Base image | `gcr.io/distroless/base-nossl-debian12` |
|
|
| Entrypoint | `/app/ai-teacher-backend` (native executable) |
|
|
| Exposed port | `8080` |
|
|
| Architecture | `linux/amd64` (matches build host) |
|
|
| Required env vars | Same as JVM mode (`SPRING_DATASOURCE_URL`, `OPENAI_API_KEY`, etc.) |
|
|
|
|
## REST API Contract
|
|
|
|
Unchanged — the native image exposes the same HTTP API as the JVM image:
|
|
|
|
- `GET /api/v1/books`
|
|
- `POST /api/v1/books` (multipart PDF upload)
|
|
- `DELETE /api/v1/books/{id}`
|
|
- `POST /api/v1/chat`
|
|
- `GET /api/v1/chat/history`
|
|
|
|
All endpoints use the same request/response schemas.
|