Payara Server Maven Plugin

Payara Server provides a Maven plugin that can start and stop the server and deploy Jakarta EE applications.

The plugin requires JDK 17 or higher.

Configurable Goals

`start`

Aim: This goal starts Payara Server with the specified configuration. Usage: mvn payara-server:start

Example:

<plugin>
    <groupId>fish.payara.maven.plugins</groupId>
    <artifactId>payara-server-maven-plugin</artifactId>
    <version>${payara.server.maven.plugin.version}</version>
    <executions>
        <execution>
            <goals>
                <goal>start</goal>
            </goals>
        </execution>
    </executions>
    <configuration>
        <payaraServerVersion>7.2025.1</payaraServerVersion>
        <javaHome>/path/to/Java/Executable</javaHome>
        <contextRoot>myApp</contextRoot>
    </configuration>
</plugin>

Common Configuration:

The following properties allow customization of local and remote deployments:

|immediateExit | |payara.immediate.exit | |PAYARA_IMMEDIATE_EXIT | |false | |If Payara Server is executed in daemon mode, the executor thread will wait for the ready message before shutting down its process. By setting immediateExit to true you can skip this and instantly interrupt the executor thread. |

|browser | |payara.browser | |PAYARA_BROWSER | |System default browser | |Specifies the browser used for live reload. If not explicitly set, Payara selects the best available browser based on the system: Chrome (if installed), then Firefox, followed by the system default—Edge on Windows, Safari on macOS, and Firefox on Linux. |

|webappDirectory | | | |${project.build.directory}/${project.build.finalName} | |The directory where the web application is built. |

Local Configuration:

The following properties allow customization of deployments to local instance.

|artifactItem | | | |none | |Defines payara-server artifact with its coordinates. Specified artifact should be available in local maven repository. |

|javaCommandLineOptions | | | |none | |Defines a list of command line options that will be passed to java executable. Command line options can either be defined as key-value pairs or just as list of values. key-value pairs will be formatted as key=value. | |=== |

Remote Configuration:

The following properties allow customization of deployments to remote instance.

`dev`

Aim: The dev goal is designed to streamline development by enabling exploded, autoDeploy, liveReload, keepState, and trimLog to true, which facilitates automatic compilation and deployment when saving files, resulting in faster iterations and a more efficient development workflow.

Usage:

mvn payara-server:dev

The dev goal is an extended goal of start and is pre-configured for developing web applications in development mode which is equivalent to starting the Payara Server instance using the following command:

mvn payara-server:start -DautoDeploy=true -DliveReload=true -Dexploded=true -DkeepState -DtrimLog=true

Features in Dev Mode:

Auto Deploy: The AutoDeploy feature enables automatic compilation and deployment of the application upon saving files within the project structure. Enabled by setting autoDeploy=true.

The AutoDeploy feature relies on Java’s WatchService to monitor changes in source directories, enabling continuous build and reload using Maven’s Invoker. It dynamically modifies Maven goals based on file modifications, supports asynchronous execution for concurrent build tasks, and includes specifics for tracking changes in source, resources, and test directories.
Live Reload: The LiveReload feature automatically refreshes the browser upon redeployment.
- liveReload Property: Enables or disables automatic browser refresh on redeployment. The liveReload property is set to true by default in the dev goal and false in the start goal.
- browser Property: The browser property offers seamless configuration. If not specified, the system prioritizes Chrome and Firefox, gracefully falling back to Edge on Windows, Safari on macOS, or Firefox on other platforms. This improvement simplifies setup - no need to worry about specifying a browser; it adapts based on your system.
- Cached Last Accessed URL: The last accessed Payara Server URL is stored in the payara-maven-config.properties file within the system’s temporary directory. This ensures accessibility across application restarts, and eliminating the need for users to manually navigate back to the last accessed URL. This streamlined approach enhances the overall user experience by maintaining continuity and reducing manual intervention after each restart.
Persistent Session State: The keepState property allows for the persistence of session state across multiple re-deployments during the development process. Enabled by default in the dev goal and disabled in the start goal.
Readable Logging: The trimLog property refactors the log format for improved readability. Enabled by default in the dev goal and disabled in the start goal.

All listed features are enabled by default in the dev mode.

Supported Keywords

The Payara Server Maven plugin provides a built-in CLI interface that accepts specific keywords to interact with a running Payara Server instance. These commands can be used via terminal input.

asadmin <command> Executes the specified asadmin subcommand. This is only available when the server manager is an instance of a local server.
```
Example:
[source,shell]
----
asadmin list-applications
----
```
deploy Deploys the current application to the running server instance.
undeploy Undeploys the current application from the running server instance.
exit Exits the CLI session and terminates the running Payara server process.

AI Agent Query

If the AI agent is enabled in the plugin configuration, the CLI accepts **any natural language query**.
The query will be interpreted by the AI and responded to accordingly, based on the current context.

The predefined keywords (asadmin, deploy, undeploy, exit) will take precedence over AI interpretation if matched.

AI Agent (Experimental)

The AI Agent is an experimental feature in the Payara Server Maven plugin that brings intelligent automation and observability to Jakarta EE application development. It is enabled by default in dev mode and disabled in other modes for safety. To enable it manually, set the payara.ai.agent system property or the PAYARA_AI_AGENT environment variable to true.

Capabilities

The AI Agent enhances the developer experience by interpreting natural language instructions and extracting contextual insights from the running server. Key features include:

Generating and explaining asadmin commands from plain English instructions.
Querying server configuration and runtime state via the Domain REST endpoints and JMX MBeans.
Executing safe, read-only asadmin commands, such as listing deployed applications or viewing JDBC connection pool status.
Parsing and summarizing server logs and key configuration files like domain.xml to surface relevant insights.
Offering intelligent prompts and auto-completions for common server administration and troubleshooting tasks.

Configuration Properties

The AI Agent can be customized using the following properties:

Usage Context

The AI Agent operates best during development, local testing, or in isolated environments. It is not recommended for use in production due to its access to sensitive runtime data and its experimental nature. By integrating AI-driven insights into the Payara tooling, the AI Agent aims to streamline operations, accelerate diagnostics, and boost developer productivity.

As this is an experimental feature, usage and API compatibility may change in future versions.

Payara Community Documentation

Payara Platform