Payara Quick Start Guide (en)

This article is revised and English transleted of the post 3rd December 2016.

Recently, Payara users are growing near by me. Most of them migrate from GlassFish, but it's certainly that Payara is the first Java EE server for someone. Then I note minimum instruction for using Payara.

0. Requirements

0.1. JDK

Payara is required JDK 7, or JDK 8 Update 20 or later. About JDK's set up is omitted because it's dependent with target OS. But I suggest to use the newest as possible. Remember setting path to JVM (java / java.exe). Attention: Payara ignores JAVA_HOME environment variable.

0.2. Network settings

In case of some OS, almost listen ports are closed in default. If your environment is such a thing, you need to add a settings of listen ports. Payara listens mainly TCP 4848, 8080 and 8181 ports. In addition to enable Hazelcast, you need to open 5900 and later ports (maximum 5999). Note: To use Payara Micro, Hazelcast is enabled in default.

1. Instruction of development environment

1.1. Downloading Payara Server

Download Payara Server from http://www.payara.fish/downloads (If you need Multi-Language edition, Access to http://www.payara.fish/all_downloads). When to download, you don't any registrations. Even if you use Payara Micro as operation, it's easy to develop applications on Payara Server.

In case of Payara 4.1.1.171.1 (latest release at the time), you may select following one;

  • Payara 4.1.1.171.1 (Full) : payara-4.1.1.171.1.zip
  • Payara-Web 4.1.1.171.1 (Web Profile) : payara-web-4.1.1.171.1.zip
  • Payara-ML 4.1.1.171.1 (Multi-Language Full) : payara-ml-4.1.1.171.1.zip
  • Payara-Web-ML 4.1.1.171.1 (Multi-Language Web Profile) : payara-web-ml-4.1.1.171.1.zip

I suggest you may select Full Platform i.e. payara-4.1.1.171.1.zip for development. If you need Web Profile (e.g. planning to use Payara Micro in operation), restricted by Maven dependency (javax:javax-ee-web:7.0).

1.2. Installation of Payara Server

Extract payara-4.1.1.171.1.zip to any directory. But on Windows, avoid to the directory it's named spaces (e.g. C:\Program Files). If you are an administrator of the computer, extract to C:\ (on Windows) or /opt (on Linux/Solaris) for ease. Then Payara Server installed on C:\payara41 (on Windows) or /opt/payara41 (on Linux/Solaris).

If you're not an administrator, it may extract to %USERPROFILE% (C:\Users\username) on Windows or $HOME (/export/home/username or /home/username) on Linux/Solaris.

1.3. IDE Settings for Payara Server

Payara Server is controlled by major IDEs with some settings.

1.3.1. Eclipse

In case of Eclipse , you should GlassFish Tools contained in Oracle Enterprise Pack for Eclipse (OEPE) (It's no problem to contain other plugins of OEPE). Choose GlassFish 4 for server type, and input C:\payara41\glassfish (Windows) or /opt/payara41/glassfish (Linux/Solaris) for installed directory. Pay attention to setting it glassfish directory that is a sub directory of Payara's install directory. (There's Nucleus, the core modules of Payara) Other choices may be still in defaults.

You may also obtain GlassFish Tools from Eclipse Marketplace.

1.3.2. NetBeans

NetBeans can integrate with GlassFish using a built in feature. Add a server instance in Service - Servers. Choose GlassFish Server as server type, and input C:\payara41 (Windows) or /opt/payara41 (Linux/Solaris) as installed directory. Other choices may be still in defaults. Note: NetBeans can download a server instance if not exists. But it never use for Payara because it will download GlassFish.

1.3.3. IntelliJ IDEA

IntelliJ IDEA can integrate with GlassFish using a built in feature. At first, choice Glassfish Server on Default Settings -> Build, Execution, Deployment -> Application Servers. And then required Glassfish Home directory, input C:\payara41 (Windows) or /opt/payara41 (Linux/Solaris). Other choices may be still in defaults.

1.4. Using Payara Server as development environment

Payara Server in development is usually started, stopped and deployed from IDE. Thus you may know following three operations for Payara Server.

  • payara41/bin/asadmin start-domain to start Payar Server
  • payara41/bin/asadmin stop-domain to stop Payara Server
  • Using admin console http://localhost:4848/ to operate Payara Server during Payara Server is running

Payara's admin console is such a Web UI;

payara-admingui-top.png
figure 1 - Payara Server Console (Dev.)

2. Instruction of operating envirionment

2.1. Downloading Payara Server

Download Payara Server from http://www.payara.fish/downloads as same as instruction of developing envirionment.

In case of Payara 4.1.1.171.1 (latest release at the time), you may select following one;

  • Payara 4.1.1.171.1 (Full) : payara-4.1.1.171.1.zip
  • Payara-Web 4.1.1.171.1 (Web Profile) : payara-web-4.1.1.171.1.zip
  • Payara-ML 4.1.1.171.1 (Multi-Language Full) : payara-ml-4.1.1.171.1.zip
  • Payara-Web-ML 4.1.1.171.1 (Multi-Language Web Profile) : payara-web-ml-4.1.1.171.1.zip

In case of operating environment, you should select to install either Full Platform or Web Profile. For many purposes, Web Profile is better. If you want to use APIs without Web Profile, you need to install Full Platform.

See also following slides about Web Profile.

It's easy to operate Payara Server using mainly admin console. You may use localized admin console to convenient. Then you may install Web Profile Multi-language : payara-ml-4.1.1.171.1.zip.

Tips: When you post an issue in trouble, it's precondition to use English UI. Thus I suggest you also prepare English version for reproducing tests.

2.2. Installation of Payara Server

Extract payara-4.1.1.171.1.zip to any directory. But on Windows, avoid to the directory it's named spaces (e.g. C:\Program Files). If you are an administrator of the computer, extract to C:\ (on Windows) or /opt (on Linux/Solaris) for ease. Then Payara Server installed on C:\payara41 (on Windows) or /opt/payara41 (on Linux/Solaris).

2.3. Enable to remote access to Payara Server

2.3.1. Setting the admin password

Payara is not set the admin pasword in default. It's mean that remote access to Payara Server is disabled in default. Then, at first, you should set the admin password. Use asadmin change-admin password command to set the admin password. see follows;

C:\payara41\bin>asadmin change-admin-password
Enter admin user name [default: admin]>
Enter the admin password>
Enter the new admin password>
Enter the new admin password again>
Command change-admin-password executed successfully.

asadmin change-admin-password command works two tasks, (1) set admin user name, (2) set or change admin password. The input is following items;

  1. admin user name: If use 'admin', you may empty this item
  2. the admin password: current password; In default, it must set empty because the default admin password is empty
  3. the new admin password: input the password
  4. the new admin password again: input the password again

Attention: The first item is admin user name (not password), don't miss.

2.3.2. Enable secure administration

Payara rejects remote access via HTTP (plain text), so you should enable secure administration (remote access via HTTPS). To enable or disable secure administration is needed to run Payara Server, you start to use asadmin start-domain command.

Then you enable secure administration using asadmin enable-secure-admin command. the command requires admin user name and password. because you should set the admin password the previous step.

C:\payara41\bin>asadmin enable-secure-admin
Enter admin user name>  admin
Enter admin password for user "admin">
You must restart all running servers for the change in secure admin to take effect.
Command enable-secure-admin executed successfully.

After secure administration is enabled, you have to reboot Payara Server. You may use convenient command, asadmin restart-domain.

To enable and disable secure administration is also supported by admin console. But Web browser maybe disabled on Payara Server's machine. So I suggest to use command line.

2.4. Using Payara Server as operating envirionment

It's easest that (1) Start to asadmin start-domain command, (2) Stop to asadmin stop-domain command, (3) Other operations are on admin console. Admin console URL via remote access is https://<hostname>:4848/ and require 'User Name' (admin user name, 'admin' in default) and 'Password' (the admin password).

payara-admingui-login.png
figure 2 - Payara Server Log-in (Admin Console)

Set enable-secure-admin when to enable remote access. It means that you access to admin console via HTTPS (HTTP over SSL/TLS) instead of HTTP and using encrypted connection. (To access to admin console is restricted via HTTPS since GlassFish 3.1.2?) Web browsers will block to access admin console once because key store of Payara Server is not ready. But even if it's in intranet, you can ignore and force access to admin console.

payara-admingui-top.png
figure 3 - Payara Server Console (Ops.)

3. Starting up Payara Micro

3.1. Downloading Payara Micro

3.1.1. Download from the Web site

Download Payara Micro 171 (payara-micro-4.1.1.171.1.jar) from http://www.payara.fish/downloads (If need, you may change the file name to any).

3.1.2. Maven integration

Add dependencies to pom.xml in a Maven Project as following. Then Payara Micro is downloaded automatically from Maven Central Repository.

<dependencies>
  <groupId>fish.payara.extras</groupId>
  <artifactId>payara-micro</artifactId>
  <version>4.1.1.171.1</version>
</dependencies>

3.2. Using Payara Micro as operating environment

3.2.1. Run Payara Micro

At first, prepare a WAR file of Web application; webapp.war. Basically you develop a Web application using Payara Server even if you run it on Payara Micro.

And then, run Payara Micro on a terminal.

$ java -jar payara-micro-4.1.1.171.1.jar --deploy webapp.war

Ctrl + C to exit.

Payara Micro is enabled Hazelcast clustering in default. (Payara Server is disabled in default) Usually it need not change. If you set with --noCluster option to disable Hazelcast clustering and start up first such a little. But --noCluster option stops whole of Hazelcast, it's disabled not only automatic clustering but also JCache.

$ java -jar payara-micro-4.1.1.171.1.jar --deploy webapp.war --noCluster

3.2.2. Create Uber Jar and run

You can create Uber Jar (webapp.jar) from Payara Micro and WAR files.

$ java -jar payara-micro-4.1.1.171.1.jar --deploy webapp.war --packageUberJar webapp.jar

After create Uber Jar, you run it directly.

java -jar webapp.jar

Uber Jar is Payara Micro includes WAR files. You may use various options of Payara Micro, and Ctrl + C to exit.

4. Conclusion

Payara is growing day by day. Recently it is not only "well-maintained GlassFish" but also fitting for commertial use. Now it's features are so many and powerful, but it's minimal instruction to use is kept simple. I wish Payara is used many people -- from newbies to experts.