Adrien
d8bcdce879
commit 0d624137c2557c6eeb87020749e4977b821c2b5c Author: Adrien <adrien.cesaro@proton.me> Date: Thu Apr 9 11:55:22 2026 +0200 backend native image setup
82 lines
2.1 KiB
Markdown
82 lines
2.1 KiB
Markdown
# 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.
|