Squashed commit of the following:

commit 0d624137c2557c6eeb87020749e4977b821c2b5c Author: Adrien <adrien.cesaro@proton.me> Date: Thu Apr 9 11:55:22 2026 +0200 backend native image setup
2026-04-09 12:05:02 +02:00
parent aee6a9dfba
commit d8bcdce879
17 changed files with 1285 additions and 6 deletions
@@ -0,0 +1,81 @@
+# Quickstart: Native Image Build & Deploy
+
+**Branch**: `005-native-image-deployment` | **Date**: 2026-04-07
+
+## Prerequisites
+
+- GraalVM JDK 25 CE or Oracle GraalVM 25 installed and set as `JAVA_HOME`
+- Docker daemon running (for `jib:dockerBuild`)
+- Maven 3.9+
+
+```bash
+# Install GraalVM 25 CE via sdkman
+sdk install java 25-graalce
+sdk use java 25-graalce
+
+# Verify
+java -version            # should show GraalVM 25
+native-image --version   # should show GraalVM 25
+```
+
+## Build Native Docker Image (local)
+
+```bash
+cd backend
+
+# Build native executable AND package into local Docker image
+mvn -Pnative package jib:dockerBuild
+
+# The image is now available locally
+docker images | grep ai-teacher-backend
+```
+
+## Run the Full Stack (native)
+
+```bash
+# From repo root — starts PostgreSQL + native backend
+docker compose -f docker-compose.native.yml up
+```
+
+Access the app at `http://localhost:8080`.
+
+## Build and Push to Registry (CI)
+
+```bash
+mvn -Pnative package jib:build \
+  -Djib.to.image=ghcr.io/your-org/ai-teacher-backend:native-latest \
+  -Djib.to.auth.username=$REGISTRY_USER \
+  -Djib.to.auth.password=$REGISTRY_TOKEN
+```
+
+## JVM Build (unchanged)
+
+```bash
+# Default profile — no GraalVM required
+cd backend
+mvn package -DskipTests
+
+java -jar target/ai-teacher-backend-*.jar
+```
+
+## Environment Variables (both JVM and native)
+
+| Variable | Description |
+|----------|-------------|
+| `SPRING_DATASOURCE_URL` | PostgreSQL JDBC URL |
+| `SPRING_DATASOURCE_USERNAME` | DB user |
+| `SPRING_DATASOURCE_PASSWORD` | DB password |
+| `OPENAI_API_KEY` | OpenAI API key |
+| `AWS_ACCESS_KEY_ID` | S3 access key (if S3 storage enabled) |
+| `AWS_SECRET_ACCESS_KEY` | S3 secret key |
+| `AWS_REGION` | S3 region |
+
+## Troubleshooting
+
+**Build fails with "ImageGenerationFailed"**: Ensure `native-image` is on `PATH` and
+`JAVA_HOME` points to GraalVM 25, not a regular JDK.
+
+**Missing resource at runtime**: Add the resource pattern to `NativeHintsConfig` and rebuild.
+
+**ClassNotFoundException at runtime**: Register the class in `NativeHintsConfig` with
+`MemberCategory.INVOKE_PUBLIC_CONSTRUCTORS` and rebuild.