# 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.