Basic Deployment

Make sure your build.gradle contains the following code:

vaadin {
    optimizeBundle = false
}

It is required for production builds.

Creating Executable JAR

Open the terminal in the project root folder and execute the following command:

Linux and macOS
./gradlew -Pvaadin.productionMode=true bootJar
Windows
gradlew "-Pvaadin.productionMode=true" bootJar

The executable JAR name will consist of the name and the version of your project. For example, if you specified the following in your settings.gradle:

rootProject.name = 'myapp'

and in your build.gradle:

group = 'com.company'
version = '0.0.1-SNAPSHOT'

then the JAR name will be myapp-0.0.1-SNAPSHOT.jar.

The executable JAR file is created in the /build/libs folder. You can copy it anywhere and run as follows:

java -jar myapp-0.0.1-SNAPSHOT.jar

If you want to customize the packaging process or create a deployable WAR file, refer to the Spring Boot Documentation.

Creating Docker Image

Using Dockerfile

The most standard and reliable way of creating a Docker image is to use a Dockerfile. It works in any environment and can be adjusted for any requirements. The simplest Dockerfile is shown below:

Dockerfile
FROM eclipse-temurin:21-jre-alpine
COPY build/libs/*.jar app.jar

ENTRYPOINT ["java", "-jar", "/app.jar"]

To build an image using a Dockerfile, do the following:

  1. Create a Dockerfile in the project root folder.

  2. Build an executable JAR file as described in the previous section.

  3. Build an image, executing the following command in the project root:

    docker build -t IMAGE_NAME .

    Replace IMAGE_NAME with your preferred image name.

Using bootBuildImage

The Gradle’s bootBuildImage task allows you to build an optimized image.

Open the terminal in the project root folder and execute the following command:

Linux and macOS
./gradlew -Pvaadin.productionMode=true bootBuildImage
Windows
gradlew "-Pvaadin.productionMode=true" bootBuildImage

By default, the image will be created with the name of your project and tag which is equal to you project’s version.

For example, if you specified the following in your settings.gradle:

rootProject.name = 'myapp'

and in your build.gradle:

group = 'com.company'
version = '0.0.1-SNAPSHOT'

then the created image will be myapp:0.0.1-SNAPSHOT.

If you are using the Grid Export Actions add-on for exporting to Excel, you may need to add the following configuration to your build.gradle to make sure the image includes all required fonts:

tasks.named("bootBuildImage") {
    builder = "paketobuildpacks/builder-jammy-full"
}

You can find more information on image generation and customization in the Spring Boot Documentation.

Deploying WAR

If you want to build a WAR file for deployment to an application server, follow these steps:

  1. Make sure your main application class extends SpringBootServletInitializer, for example:

    @SpringBootApplication
public class MyApplication
        extends SpringBootServletInitializer
        implements AppShellConfigurator {
    // ...
}

  2. Add the war plugin to the plugins section of your build.gradle file:

    plugins {
    // ...
    id 'war'
}

  3. Open the terminal in the project root folder and execute the following command:

    Linux and macOS
    ./gradlew -Pvaadin.productionMode=true bootWar
    Windows
    gradlew "-Pvaadin.productionMode=true" bootWar

The WAR file is created in the /build/libs folder. The file name is generated as described in the previous section.

You need at least Tomcat 10 to run applications because since Jmix 2.0 they require support for Jakarta EE 9 (jakarta.* namespace), see Tomcat documentation for details.

Use the latest Tomcat 10 to deploy Jmix WAR.

Using JNDI Data Source

When deploying your application as a WAR, you can use a JNDI data source provided by the application server to externalize connection settings.

See below how to configure the main DataSource of your application for development and production environments using the Spring’s profiles feature.

  1. In your main application class, add @Profile("!prod") annotation to dataSourceProperties and dataSource methods to make sure these beans are created only in development environment:

    @Profile("!prod")
@Bean
@Primary
@ConfigurationProperties("main.datasource")
DataSourceProperties dataSourceProperties() {
    return new DataSourceProperties();
}

@Profile("!prod")
@Bean
@Primary
@ConfigurationProperties("main.datasource.hikari")
DataSource dataSource(DataSourceProperties dataSourceProperties) {
    return dataSourceProperties.initializeDataSourceBuilder().build();
}

  2. Add a method creating a DataSource bean for the production environment:

    @Profile("prod")
@Bean(name = "dataSource")
@Primary
DataSource prodDataSource(ApplicationContext context) {
    JndiDataSourceLookup lookup = new JndiDataSourceLookup();
    DataSource dataSource = lookup.getDataSource("java:comp/env/jdbc/demo"); (1)

    // to avoid org.springframework.jmx.export.UnableToRegisterMBeanException:
    for (MBeanExporter mbeanExporter : context.getBeansOfType(MBeanExporter.class).values()) {
        if (JmxUtils.isMBean(((Object) dataSource).getClass())) {
            mbeanExporter.addExcludedBean("dataSource");
        }
    }

    return dataSource;
}
    1 JNDI name of the data source provided by the application server.

  3. When running the application server, set active profile to prod in spring.profiles.active application property.

Below is an example of configuring Tomcat for deploying a demo.war application.

  1. Copy demo.war to tomcat/webapps folder.

  2. Create tomcat/bin/setenv.sh file with the following content:

    CATALINA_OPTS="-Dspring.profiles.active=prod"

  3. Create tomcat/conf/Catalina/localhost/demo.xml file defining the data source and set appropriate database connection parameters (XML file name must be the same as your WAR name):

    <Context>
    <Resource type="javax.sql.DataSource"
              name="jdbc/demo"
              driverClassName="org.postgresql.Driver"
              url="jdbc:postgresql://localhost/demo"
              username="root"
              password="root"
              maxIdle="2"
              maxTotal="20"
              maxWaitMillis="5000"
    />
</Context>

    Notice that the name attribute of the Resource element defines the JNDI name used in the JndiDataSourceLookup.getDataSource() method when creating the DataSource bean.

  4. Copy an appropriate JDBC driver file (for example, postgresql-42.2.9.jar) to tomcat/lib.

When you start Tomcat, the application will use the data source defined in the tomcat/conf/Catalina/localhost/demo.xml file.