Migrating to Baseless Image Tiles

This guide provides instructions for migrating from java-service-base-dependent tiles to the new "baseless" variants introduced in NGSS Maven Tiles 1.9.0.

Migration Timeline

With java-service-base being deprecated as of 8/19/2025 and scheduled for retirement on 2/19/2026, migrating to baseless tiles is essential for staying up to date with base image versions.

Baseless tiles eliminate the dependency on java-service-base and provide greater flexibility in base image selection while maintaining all NGSS build conventions.

Overview

The baseless tiles provide the same functionality as their java-service-base-dependent counterparts but allow you to specify any MAP Java base image directly in your project’s pom.xml.

Tile Name Changes

Legacy Tile (Deprecated) New Baseless Tile

docker-maven-plugin-tile

docker-maven-plugin-baseless-tile

jib-maven-plugin-tile

jib-maven-plugin-baseless-tile

Maven Properties

The baseless tiles require specific Maven properties to be configured in your project’s pom.xml. This section details all available properties and their usage.

Required Properties

base.image

Required. Specifies the base container image for your service build.

This property replaces the built-in default of java-service-base and gives you control over base image selection. For most cases, you should specify official MAP-based images.

Examples:
<!-- MAP-based Images -->
<base.image>base/java21-jre:1.3.0</base.image>
<base.image>base/java17-jre:2.3.0</base.image>

Optional Properties

Script Directory Overrides

Application images require custom startup scripts to be defined for the image build.

The following properties allow you to customize the source location (relative to the service module directory) for these scripts when the default locations don’t meet your project structure needs:

docker.src.dir

Optional. Override source location for docker-maven-plugin-baseless-tile container scripts.

Default: src/main/docker

<docker.src.dir>custom/docker/scripts</docker.src.dir>
jib.src.dir

Optional. Override source location for jib-maven-plugin-baseless-tile container scripts.

Default: src/main/jib

<jib.src.dir>custom/jib/scripts</jib.src.dir>
See Step 3: Copy Required Scripts for instructions on copying default script files to your project

Complete Properties Example

<properties>
    <!-- Required: Base image for container builds -->
    <base.image>base/java21-jre:1.3.0</base.image>

    <!-- Optional: Custom script directories (uncomment if needed) -->
    <!-- <docker.src.dir>src/main/docker</docker.src.dir> -->
    <!-- <jib.src.dir>src/docker</jib.src.dir> -->

    <!-- Required: NGSS Tiles version (1.9.0+ for baseless support) -->
    <ngss-tiles.version>1.9.0</ngss-tiles.version>

    <!-- Other project properties... -->
</properties>

Migration Steps

Step 1: Update Tile References

In your project’s pom.xml, update the tile names in the tiles-maven-plugin configuration:

Before (Legacy):

<plugin>
    <groupId>io.repaint.maven</groupId>
    <artifactId>tiles-maven-plugin</artifactId>
    <configuration>
        <tiles>
            <tile>gov.va.mobile.tools.maven:docker-maven-plugin-tile:${ngss-tiles.version}</tile>
            <!-- OR -->
            <tile>gov.va.mobile.tools.maven:jib-maven-plugin-tile:${ngss-tiles.version}</tile>
        </tiles>
    </configuration>
</plugin>

After (Baseless):

<plugin>
    <groupId>io.repaint.maven</groupId>
    <artifactId>tiles-maven-plugin</artifactId>
    <configuration>
        <tiles>
            <tile>gov.va.mobile.tools.maven:docker-maven-plugin-baseless-tile:${ngss-tiles.version}</tile>
            <!-- OR -->
            <tile>gov.va.mobile.tools.maven:jib-maven-plugin-baseless-tile:${ngss-tiles.version}</tile>
        </tiles>
    </configuration>
</plugin>

Step 2: Define Base Image Property

Add the base.image property to your project’s pom.xml <properties> section:

<properties>
    <!-- Specify your base image -->
    <base.image>base/java21-jre:1.3.0</base.image>

    <!-- Other existing properties... -->
    <ngss-tiles.version>1.9.0</ngss-tiles.version>
</properties>

Step 3: Copy Required Scripts

The baseless tiles require container startup scripts to be present in your project. Copy the appropriate scripts based on which tile you’re using.

Required scripts

  • entrypoint.sh - Main container entrypoint with dependency checking and configuration management

  • printEnv.sh - Environment variable debugging utility

  • run-service.sh - Service startup script

  • setEnv.sh - Environment configuration with Consul integration

If this is a multi-module project, be sure to copy to the service app module directory (usually named the same as the project).

For Docker Maven Plugin Projects

Download all scripts from here and copy to your service module’s src/main/docker/ directory.

# Create the src/docker directory if it doesn't exist
mkdir -p /path/to/project/[service_module]/src/main/docker

# Unzip the scripts to the src/main/docker directory
unzip docker-scripts.zip -d /path/to/project/[service_module]/src/main/docker

For Jib Maven Plugin Projects

Download all scripts from here and copy to your service module’s src/main/jib/ directory:

# Create the src/docker directory if it doesn't exist
mkdir -p /path/to/project/[service_module]/src/main/jib

# Copy the required scripts
unzip jib-scripts.zip -d /path/to/project/[service_module]/src/main/jib

Migration Examples

Complete Docker Maven Plugin Migration

Before:

<project>
    <properties>
        <ngss-tiles.version>1.8.2</ngss-tiles.version>
    </properties>

    <build>
        <plugins>
            <plugin>
                <groupId>io.repaint.maven</groupId>
                <artifactId>tiles-maven-plugin</artifactId>
                <configuration>
                    <tiles>
                        <tile>gov.va.mobile.tools.maven:docker-maven-plugin-tile:${ngss-tiles.version}</tile>
                        <!-- other tiles -->
                    </tiles>
                </configuration>
            </plugin>
        </plugins>
    </build>
</project>

After:

<project>
    <properties>
        <!-- Specify base image explicitly -->
        <base.image>base/java21-jre:1.3.0</base.image>
        <!-- Update to version with baseless tiles -->
        <ngss-maven-tiles.version>1.9.0</ngss-maven-tiles.version>
    </properties>

    <build>
        <plugins>
            <plugin>
                <groupId>io.repaint.maven</groupId>
                <artifactId>tiles-maven-plugin</artifactId>
                <configuration>
                    <tiles>
                        <tile>gov.va.mobile.tools.maven:docker-maven-plugin-baseless-tile:${ngss-maven-tiles.version}</tile>
                        <!-- other tiles -->
                    </tiles>
                </configuration>
            </plugin>
        </plugins>
    </build>
</project>
New files
📒 projectroot
  📁 service-module (if multimodule project)
    📁 src
      📁 main
        📁 docker
          📄 entrypoint.sh
          📄 printEnv.sh
          📄 run-service.sh
          📄 setEnv.sh

Complete Jib Maven Plugin Migration

Before:

<project>
    <properties>
        <ngss-maven-tiles.version>1.8.2</ngss-maven-tiles.version>
    </properties>

    <build>
        <plugins>
            <plugin>
                <groupId>io.repaint.maven</groupId>
                <artifactId>tiles-maven-plugin</artifactId>
                <configuration>
                    <tiles>
                        <tile>gov.va.mobile.tools.maven:jib-maven-plugin-tile:${ngss-maven-tiles.version}</tile>
                        <tile>gov.va.mobile.tools.maven:helm-tile:${ngss-maven-tiles.version}</tile>
                    </tiles>
                </configuration>
            </plugin>
        </plugins>
    </build>
</project>

After:

<project>
    <properties>
        <!-- Specify base image explicitly -->
        <base.image>base/java21-jre:1.3.0</base.image>
        <!-- Update to version with baseless tiles -->
        <ngss-maven-tiles.version>1.9.0</ngss-maven-tiles.version>
    </properties>

    <build>
        <plugins>
            <plugin>
                <groupId>io.repaint.maven</groupId>
                <artifactId>tiles-maven-plugin</artifactId>
                <configuration>
                    <tiles>
                        <tile>gov.va.mobile.tools.maven:jib-maven-plugin-baseless-tile:${ngss-maven-tiles.version}</tile>
                        <tile>gov.va.mobile.tools.maven:helm-tile:${ngss-maven-tiles.version}</tile>
                    </tiles>
                </configuration>
            </plugin>
        </plugins>
    </build>
</project>
New files
📒 projectroot
  📁 service-module (if multimodule project)
    📁 src
      📁 main
        📁 jib
          📄 entrypoint.sh
          📄 printEnv.sh
          📄 run-service.sh
          📄 setEnv.sh

Base Image Options

Standard NGSS Base Images

For continuity with existing builds, use the current MAP standard images for the Java version needed:

<properties>
    <!-- Current stable versions -->
    <base.image>base/java21-jre:1.3.0</base.image>

    <!-- OR -->

    <base.image>base/java17-jre:2.3.0</base.image>
</properties>

Validation

After migration, validate your changes:

Build Verification

# Verify successful build with new baseless tiles
mvn clean install

Troubleshooting

Common Issues

Service fails to start successfully

If podLogs/your-service-v1-xxxxxxx.log does not contain the expected output (for example it’s empty or there are no startup commands), then this likely means the startup scripts are not being copied into the correct location in the image.

Solution

If you haven’t overridden the <jib.src.dir> or <docker.src.dir> property, verify that the four script files are present in the projectRoot/[service_module]/src/main/jib or projectRoot/[service_module]/src/main/docker directory.

See Step 3: Copy Required Scripts for detailed instructions if needed.

Getting Help

If you encounter issues during migration:

  1. Check the base image exists and is accessible

  2. Verify your tiles version is 1.9.0 or later

  3. Ensure all required properties are defined

  4. Review the container build logs for detailed error messages

Migration Checklist

  • Update tile names from legacy to baseless variants

  • Add base.image property to pom.xml

  • Copy required scripts into project

  • Update NGSS Maven Tiles version to 1.9.0+

  • Test build locally with mvn clean install

Next Steps

After successfully migrating to baseless tiles:

  1. Consider migrating to NGSS Maven Tiles 2.x for additional benefits

  2. Update team documentation with new tile configuration

  3. Plan regular base image updates independent of tiles updates