Deployment & Packaging

<!-- pom.xml — make Maven produce ONE runnable "fat" (uber) JAR -->
<!-- A fat JAR bundles your code AND every dependency into a single file, -->
<!-- so the server only needs Java installed — nothing else to download.  -->
<project>
    <groupId>com.example</groupId>
    <artifactId>myapp</artifactId>
    <version>1.0.0</version>
    <packaging>jar</packaging>

    <build>
        <finalName>app</finalName>            <!-- output is target/app.jar -->
        <plugins>
            <plugin>
                <!-- Shade merges all dependency jars into one -->
                <groupId>org.apache.maven.plugins</groupId>
                <artifactId>maven-shade-plugin</artifactId>
                <version>3.6.0</version>
                <executions>
                    <execution>
                        <phase>package</phase>          <!-- runs on 'mvn package' -->
                        <goals><goal>shade</goal></goals>
                        <configuration>
                            <transformers>
                                <!-- write Main-Class into the JAR manifest so -->
                                <!-- 'java -jar app.jar' knows where to start -->
                                <transformer
                                    implementation="org.apache.maven.plugins.shade.resource.ManifestResourceTransformer">
                                    <mainClass>com.example.App</mainClass>
                                </transformer>
                            </transformers>
                        </configuration>
                    </execution>
                </executions>
            </plugin>
        </plugins>
    </build>
</project>

$ mvn clean package -DskipTests
[INFO] --- shade:3.6.0:shade (default) @ myapp ---
[INFO] Including com.fasterxml.jackson.core:jackson-databind:jar in the shaded jar.
[INFO] Replacing original artifact with shaded artifact.
[INFO] BUILD SUCCESS

$ ls -lh target/app.jar
-rw-r--r-- 1 dev dev 14M target/app.jar     # one file, all deps inside

$ java -jar target/app.jar
Server started on http://0.0.0.0:8080

# Multi-stage Dockerfile. Stage 1 has the full JDK + Maven and is
# THROWN AWAY after the build, so its size never ships. Stage 2 is a
# tiny JRE-only image that becomes your final, deployable artifact.

# ---- Stage 1: BUILD (heavy, discarded) ----
FROM maven:3.9-eclipse-temurin-21 AS build
WORKDIR /app
COPY pom.xml .
RUN mvn dependency:go-offline -B          # cached in its own layer
COPY src ./src
RUN mvn clean package -DskipTests         # produces target/app.jar

# ---- Stage 2: RUNTIME (small, shipped) ----
FROM eclipse-temurin:21-jre-alpine        # JRE only, no compiler
WORKDIR /app
# Run as a non-root user — never run a container as root
RUN addgroup -S app && adduser -S app -G app
USER app
COPY --from=build /app/target/app.jar app.jar
EXPOSE 8080
# Container-aware JVM flags + a health probe (see sections below)
HEALTHCHECK --interval=30s --timeout=3s CMD wget -qO- http://localhost:8080/actuator/health || exit 1
ENTRYPOINT ["java", "-XX:MaxRAMPercentage=75", "-jar", "app.jar"]

$ docker build -t myapp:1.0.0 .
 => [build 5/5] RUN mvn clean package -DskipTests       38.4s
 => [stage-1 4/4] COPY --from=build /app/target/app.jar  0.1s
 => exporting to image
 => => naming to docker.io/library/myapp:1.0.0

$ docker images myapp
REPOSITORY   TAG     SIZE
myapp        1.0.0   182MB        # JRE-alpine final image (build stage discarded)

$ docker run -p 8080:8080 myapp:1.0.0
Server started on http://0.0.0.0:8080

# Spring Boot can split the fat JAR into LAYERS by how often they
# change. Dependencies (rarely change) cache separately from your
# code (changes every commit), so rebuilds only re-copy the last layer.

# ---- Build stage ----
FROM eclipse-temurin:21-jdk-alpine AS build
WORKDIR /app
COPY . .
RUN ./mvnw clean package -DskipTests
# Explode the fat JAR into its layer folders
RUN java -Djarmode=layertools -jar target/app.jar extract

# ---- Runtime stage: copy layers least-changed FIRST ----
FROM eclipse-temurin:21-jre-alpine
WORKDIR /app
COPY --from=build /app/dependencies/ ./
COPY --from=build /app/spring-boot-loader/ ./
COPY --from=build /app/snapshot-dependencies/ ./
COPY --from=build /app/application/ ./        # your code — the only layer that changes daily
EXPOSE 8080
ENTRYPOINT ["java", "org.springframework.boot.loader.launch.JarLauncher"]

$ java -Djarmode=layertools -jar target/app.jar list
dependencies
spring-boot-loader
snapshot-dependencies
application

# First build: all layers built. Change ONE line of Java and rebuild:
$ docker build -t myapp:1.0.1 .
 => CACHED [stage-1 3/6] COPY --from=build /app/dependencies/ ./   # reused!
 => CACHED [stage-1 4/6] COPY --from=build /app/spring-boot-loader/ ./
 => [stage-1 6/6] COPY --from=build /app/application/ ./   0.1s    # only this rebuilt
 => exporting to image                                     1.2s    # seconds, not minutes

# Each environment gets its own application-<profile>.properties.
# You ship ONE jar; the environment chooses the profile at runtime.
# NEVER hardcode the URL/password into the jar.

# src/main/resources/application.properties (shared defaults)
server.port=8080
server.shutdown=graceful                 # finish in-flight requests on stop

# src/main/resources/application-dev.properties
spring.datasource.url=jdbc:h2:mem:devdb
logging.level.root=DEBUG

# src/main/resources/application-prod.properties
spring.datasource.url=${DB_URL}          # read from environment variables
spring.datasource.username=${DB_USER}
spring.datasource.password=${DB_PASSWORD}
logging.level.root=WARN

# Pick the profile + inject secrets via the environment at launch:
export DB_URL="jdbc:postgresql://prod-db:5432/app"
export DB_USER="app"
export DB_PASSWORD="s3cr3t-from-vault"
SPRING_PROFILES_ACTIVE=prod java -jar app.jar

$ SPRING_PROFILES_ACTIVE=prod java -jar app.jar
 :: Spring Boot ::                (v3.3.0)
The following 1 profile is active: "prod"
HikariPool-1 - Added connection org.postgresql.jdbc.PgConnection@1a2b
Tomcat started on port 8080 (http)
Started App in 2.41 seconds (process running for 2.9)

// Add the dependency to pom.xml:
//   <dependency>
//     <groupId>org.springframework.boot</groupId>
//     <artifactId>spring-boot-starter-actuator</artifactId>
//   </dependency>
//
// application.properties — expose only what you need:
//   management.endpoints.web.exposure.include=health,info,metrics,prometheus
//   management.endpoint.health.show-details=when_authorized
//   management.endpoint.health.probes.enabled=true   # readiness + liveness
//   server.shutdown=graceful                          # finish in-flight requests
//   spring.lifecycle.timeout-per-shutdown-phase=30s

// A custom HealthIndicator — checks the database, not just "UP".
import org.springframework.boot.actuate.health.Health;
import org.springframework.boot.actuate.health.HealthIndicator;
import org.springframework.stereotype.Component;
import javax.sql.DataSource;
import java.sql.Connection;

@Component
public class DatabaseHealthIndicator implements HealthIndicator {

    private final DataSource dataSource;

    public DatabaseHealthIndicator(DataSource dataSource) {
        this.dataSource = dataSource;
    }

    @Override
    public Health health() {
        try (Connection c = dataSource.getConnection()) {
            if (c.isValid(2)) {                       // 2-second timeout
                return Health.up()
                             .withDetail("database", c.getMetaData().getDatabaseProductName())
                             .build();
            }
            return Health.down().withDetail("reason", "connection not valid").build();
        } catch (Exception e) {
            return Health.down(e).build();            // reports DOWN with the error
        }
    }
}

$ curl http://localhost:8080/actuator/health
{ "status": "UP",
  "components": {
    "db":        { "status": "UP", "details": { "database": "PostgreSQL" } },
    "diskSpace": { "status": "UP", "details": { "free": 320000000000 } }
  } }

$ curl http://localhost:8080/actuator/health/readiness
{ "status": "UP" }      # k8s only sends traffic once this is UP

// Why "wrong heap in a container" crashes apps, and how to fix it.
//
// THE TRAP: old JVMs read the HOST machine's memory, not the
// container's limit. A container capped at 512m on a 64 GB host can
// have the JVM size its heap for 64 GB -> the OS kills it (OOMKilled).
//
// THE FIX: modern JVMs (11+) are container-aware. Size the heap as a
// PERCENTAGE of the container limit, not a fixed -Xmx that you must
// keep in sync with the deployment:

// In the Dockerfile / k8s command:
//   java -XX:MaxRAMPercentage=75 -jar app.jar
//
// With a container limited to 512Mi, that gives ~384Mi of heap and
// leaves headroom for metaspace, thread stacks, and off-heap buffers.

// You can confirm what the JVM actually sees inside the container:
//   $ java -XX:+PrintFlagsFinal -version | grep -i maxheap
//   size_t MaxHeapSize = 402653184      // ~384 MiB, matches the limit

public class HeapInfo {
    public static void main(String[] args) {
        long maxMb = Runtime.getRuntime().maxMemory() / (1024 * 1024);
        int cpus   = Runtime.getRuntime().availableProcessors();
        System.out.println("JVM max heap : " + maxMb + " MB");
        System.out.println("CPUs visible : " + cpus);
    }
}

# Run inside a memory-limited container:
$ docker run --memory=512m myapp java -XX:MaxRAMPercentage=75 HeapInfo
JVM max heap : 384 MB        # sized to the container, not the 64GB host
CPUs visible : 2             # respects --cpus too

# .github/workflows/ci.yml — build, test, image, deploy on every push to main.
name: Java CI/CD
on:
  push:
    branches: [main]
  pull_request:

jobs:
  build-and-deploy:
    runs-on: ubuntu-latest
    permissions:
      contents: read
      packages: write
    steps:
      - uses: actions/checkout@v4

      - uses: actions/setup-java@v4
        with:
          java-version: '21'
          distribution: 'temurin'
          cache: maven

      - name: Compile, test, package
        run: mvn -B clean verify            # fails the build if any test fails

      - name: Log in to the container registry
        uses: docker/login-action@v3
        with:
          registry: ghcr.io
          username: ${{ github.actor }}
          password: ${{ secrets.GITHUB_TOKEN }}

      - name: Build & push image (tagged with the git SHA)
        run: |
          IMAGE=ghcr.io/${{ github.repository }}/myapp
          docker build -t $IMAGE:${{ github.sha }} -t $IMAGE:latest .
          docker push $IMAGE:${{ github.sha }}
          docker push $IMAGE:latest

      - name: Deploy to staging (main only)
        if: github.ref == 'refs/heads/main'
        run: |
          kubectl set image deploy/myapp \
            myapp=ghcr.io/${{ github.repository }}/myapp:${{ github.sha }} \
            --namespace=staging

Run mvn -B clean verify
[INFO] Tests run: 42, Failures: 0, Errors: 0, Skipped: 0
[INFO] BUILD SUCCESS
Run docker build ...
 => pushing ghcr.io/acme/myapp:9f3c1a2 ... done
Run kubectl set image ...
deployment.apps/myapp image updated
✓ Job completed in 1m 58s