Java
Version 20.0.7681
Version 20.0.7681
Java
The Java edition of includes an embedded Jetty web server so that ArcESB can be run without any external server configuration. In addition, the installation includes a .WAR file that can be deployed to any Java servlet container like Tomcat, Jetty, JBoss, WebLogic, or WebSphere.
The embedded Jetty server requires that JDK 1.8 or later is installed on the machine.
Using the Embedded Jetty Server
To start the embedded Jetty server, simply run the arcesb.jar file located in the Arc installation directory. This directory also contains a service script, which may be used to set up a systemd or init.d service on unix systems.
By default, the embedded server hosts Arc on port 8080 and only accepts plaintext connections (HTTP and not HTTPS).
After starting the server, access the web UI by directing a browser to http://localhost:8080. The default username/password credentials to access the UI are ‘admin/admin’.
Changing the Port
To configure the port that the embedded server listens on, find the ‘arcesb.xml’ file in the installation directory and open it in a text editor. Find the definition of the HTTP connector as indicated by this XML:
<New id="httpConnector" class="org.eclipse.jetty.server.ServerConnector">
Within this definition, modify the following line to change the configured port:
<Set name="port">8080</Set>
Enabling SSL/TLS
Enabling SSL/TLS connections (HTTPS) also involves modifying the ‘arcesb.xml’ file in the installation directory. Find the definition of the HTTP connector:
<New id="httpConnector" class="org.eclipse.jetty.server.ServerConnector">
Within this definition (as a direct child of the above New element), supply an sslContextFactory argument by adding the following XML block:
<Arg name="sslContextFactory">
<New id="sslContextFactory" class="org.eclipse.jetty.util.ssl.SslContextFactory">
<Set name="KeyStorePath"><SystemProperty name="arcesb.home" default="." />/keystore</Set>
<Set name="KeyStorePassword">mypassword</Set>
</New>
</Arg>
Note: The Arg element shown above must be adjacent to other Arg elements at the beginning of the connector definition. This block must not be placed after the Set element that defines the server port, for example.
The KeyStorePath element defines the location of the SSL/TLS certificate used when hosting the SSL/TLS server. The above example assumes that a ‘keystore’ folder has been created in the Arc installation directory and this folder contains a PFX certificate called ‘mycert’. The KeyStorePassword element should be set to the password that corresponds to the configured certificate.
Change User Credentials
The users that can log into the Arc web UI are defined in the ‘arcesbRealm.properties’ file in the installation directory. Each line in this file defines a user, with the following syntax:
username:password[roles]
Add a new line to define new users, or modify the existing line to change the default login credentials.
Starting and Stopping the Server
If the service script has been used to set up an ArcESB service, please reference the Running as a Service section below. Otherwise, the Running In-Process section is applicable.
Running In-Process
The embedded Jetty server is started by executing the arcesb.jar file extracted from the application download during setup. Standard Java syntax can be used to execute this file and start the server:
java -jar arcesb.jar
To stop the server, simply pass an additional parameter to this command:
java -jar arcesb.jar -stop
Running as a Service
The ArcESB service can be manipulated using standard system service commands, referencing ‘arcesb’ as the name of the service.
To start the service:
systemctl start arcesb
To stop the service:
systemctl stop arcesb
To restart the service:
systemctl restart arcesb
Configuration in Tomcat
Deploy the WAR File
You have several options for deploying a WAR file to Tomcat.
- Copy the WAR file into the webapps folder.
- Deploy the WAR file from within the management console in Tomcat. The Tomcat documentation covers this method in more detail.
It is possible that the WAR file may exceed the default maximum size allowed for file uploads in Tomcat. To overcome errors during deployment, you can edit the WEB.XML file of the manager application to allow larger files. Depending on your tomcat configuration, this file may be located in ‘/usr/share/tomcat7-admin/manager/WEB-INF’, or in another similar directory. In this file, you can change the size in bytes of the maximum allowed file size. For example, to allow deployment of a 200MB WAR file, edit the following values to change the maximum allowed file size:
<multipart-config>
<!-- 200MB max -->
<max-file-size>209715200</max-file-size>
<max-request-size>209715200</max-request-size>
<file-size-threshold>0</file-size-threshold>
</multipart-config>
Allow Tomcat Users to Access Arc
Assign the “arcesb_admin” role to the user you want to be the administrator of the application. If you are using the default user realm for Tomcat, you can add these roles by editing the tomcat-users.xml file located in CATALINA_BASE/conf/tomcat-users.xml. In the following example, the admin user has been given the necessary roles for administrative access to the application:
<user name="admin" password="admin" roles="arcesb_admin,admin-gui,manager-gui,manager-status,manager-script,manager-jmx" />
Configure Data Directory Permissions
Allow the user of the process running the Java servlet container read/write access to the data directory:
Windows: C:\\ProgramData\\ArcESB\\
Unix or Mac OS X: ~/arcesb/
Restart your Tomcat server for the changes to take effect. You can now log in to the application.
Configuration in JBoss
Deploy the WAR File
There are several ways that you can deploy a WAR file to JBoss:
- You can copy the WAR file into the
JBOSS\_HOME/standalone/deployments
subfolder. - You can also use the JBoss Administration Console to install the WAR file.
Allow Access to JBoss Users
To grant your JBoss user access to the application, assign the user the arcesb_admin
role. If you are using the default user realm for JBoss, you can add this role by running the add-user.bat file that comes with the JBoss server.
Configure Data Directory Permissions
Allow the user of the process running the Java servlet container read/write access to the data directory:
Windows: C:\\ProgramData\\ArcESB\\
Unix or Mac OS X: ~/arcesb/
Restart the server and log into the application.
Configuration in WebSphere
Create a Plan to Allow Access to WebSphere Users
To deploy the application WAR file to WebSphere, create a deployment plan. You can use the Plan Creator wizard in WebSphere to create a plan and then deploy the WAR file. You can initialize the wizard from the WebSphere administration console.
Assign the arcesb_admin
role to the user or group you will use to log into the application. The following example plan allows access to the system administrator:
<web-app xmlns="http://geronimo.apache.org/xml/ns/j2ee/web-2.0.1">
<dep:environment xmlns:dep="http://geronimo.apache.org/xml/ns/deployment-1.2">
<dep:moduleId>
<dep:groupId>default</dep:groupId>
<dep:artifactId>arcesb</dep:artifactId>
<dep:version>1371673558693</dep:version>
<dep:type>war</dep:type>
</dep:moduleId>
<dep:dependencies/>
</dep:environment>
<context-root>arcesb</context-root>
<security-realm-name>geronimo-admin</security-realm-name>
<app:security xsi:type="sec:securityType" xmlns:sec="http://geronimo.apache.org/xml/ns/security-2.0" xmlns:app="http://geronimo.apache.org/xml/ns/j2ee/application-2.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
<sec:role-mappings>
<sec:role role-name="arcesb_admin">
<sec:principal name="system" class="org.apache.geronimo.security.realm.providers.GeronimoUserPrincipal"/>
</sec:role>
<sec:role role-name="admin"/>
</sec:role-mappings>
</app:security>
</web-app>
Configure Data Directory Permissions
Allow the user of the process running the Java servlet container read/write access to the data directory:
Windows: C:\\ProgramData\\ArcESB\\
Unix or Mac OS X: ~/arcesb/
Restart the server and log into the application.
Configure the WebSphere Class Loader
In order for WebSphere to load the application resources correctly, the following steps are required:
- Within WebSphere, navigate to: Application -> Application Types -> WebSphere enterprise applications
- Select ArcESB
- Select ‘Class loading and update detection’
- Choose ‘Classes loaded with local class loader first (parent last)’
- Choose ‘Single class loader for application’
- Select OK -> Save
Configuration in WebLogic
Deploy the WAR File
To use the deployment wizard in WebLogic to deploy the WAR file:
- Click Deployments
- In the Deployments table, click Install.
- Enter the path to the WAR file and then select the WAR file from the list.
- Select Install this deployment as an application.
- Select Custom Roles: Use roles that are defined in the Administration Console; use policies that are defined in the deployment descriptor. Selecting this option allows you to manage the roles and users in WebLogic’s administration console, while WebLogic loads the roles and policies defined in the application.
Allow Access to WebLogic Users
After deploying, allow WebLogic users to access the application:
- In the WebLogic administration console, click Deployments. In the Deployments table, click the name for the application.
- Click Security > Application Scope > Roles > New.
- Add the
arcesb_admin
Web Application Scoped role and assign the role to a user or group who administers the application.
Configure Data Directory Permissions
Allow the user of the process running the Java servlet container read/write access to the data directory:
Windows: C:\\ProgramData\\ArcESB\\
Unix or Mac OS X: ~/arcesb/
Restart the server and log into the application.
Configuration in Jetty
While Arc comes with an embedded Jetty web server, the application can also be used with an external Jetty setup.
Deploy the WAR File
Copy the WAR file into Jetty’s webapps folder.
Allow Access to Jetty Users
Before starting Jetty, allow Jetty users to access the application by assigning the arcesb_admin
role. For example, you can add this role to the admin user by opening the JETTY_HOME/etc/realm.properties file. The properties for the user are composed of the password, followed by the user’s roles. For example:
admin: test,server-administrator,content-administrator,admin,user,arcesb_admin
Configure the Login Service for the Java Realm
You must also configure a login service for the application with the name ArcESBRealm
. Below is a HashLoginService example:
<Call name="addBean">
<Arg>
<New class="org.eclipse.jetty.security.HashLoginService">
<Set name="name">ArcESBRealm</Set>
<Set name="config"><Property name="jetty.home" default="."/>/etc/realm.properties</Set>
</New>
</Arg>
</Call>
Configure Data Directory Permissions
Allow the user of the process running the Java servlet container read/write access to the data directory:
Windows: C:\\ProgramData\\ArcESB\\
Unix or Mac OS X: ~/arcesb/
Restart the server and log into the application.
User Management
The Java version of the Arc web application uses forms authentication.
In Java, the user roles and passwords are managed in the Java realm configuration for your web server. Refer to your web server’s documentation from how to configure a user’s roles and password. The application requires the arcesb_admin
role.
Find and Configure the Application Directory
Arc’s Application Directory holds all of the data used by the application: configuration data, application data, logging data, certificates, etc. The default location of the Application Directory depends on whether Arc is hosted via the embedded web server or an external Java servlet container.
For the embedded web server, the Application Directory is the same as the installation directory, which by default is the following:
/opt/arcesb
When hosting Arc in an external Java servlet container, the Application Directory is relative to the home directory of the user running the server:
~/arcesb
(where ‘~’ resolves to the home directory of the user running the server hosting the application)
The Application Directory folder can be configured, which is useful in a variety of scenarios:
- Clustering multiple instances of Arc
- Using a shared network drive for application data
- Embed Arc within other systems accessing the same folders
Changing the Application Directory will move the application’s data files but will not move other application resources like .exe’s, .jar’s, etc. These resources are held in the Installation Directory, which may be the same as the Application Directory but will not change if the Application Directory is changed.
Embedded Java Server
When using the Java edition with the embedded Jetty server, the application database is configured in the arcesb.xml file found in the Installation Directory. Within this server configuration file, the AppDirectory environment variable must be set to the path to the desired directory. The following example demonstrates what this might look like when setting the data directory to a shared folder on a mounted drive:
<Call name="setInitParameter">
<Arg>AppDirectory</Arg>
<Arg>/mnt/shared/arcesb</Arg>
</Call>
If Arc can find the path, and has the appropriate permissions to read and write at the given path, it will create the data folder within the specified directory.
External Java Server
When using the Java edition with an external Java servlet (any server other than the Jetty server that is included with the application), the details of configuring the application data directory depend upon the specific servlet used. Using the syntax appropriate for the specific servlet, the AppDirectory environment variable must be set to the path to the desired directory.
If Arc can find the AppDirectory path, and has the appropriate permissions to read and write at the given path, it will create the data folder within the specified directory.
Configure the Application Database
Arc’s Application Database stores several tables of application data, including:
- Transaction Log (metadata for each transaction processed by the application)
- Application Log (application-level errors and events)
- Access Log (requests to the application’s web endpoint)
By default, Arc uses a Derby database located in the Application Directory as the Application Database, but this can be configured to use an enterprise database like MySQL or SQL Server.
Embedded Java Server
When using the Java edition with the embedded Jetty server, the application database is configured in the arcesb.xml file found in the installation directory. Within this server configuration file, the APP_DB environment variable must be set to a JDBC connection string containing the appropriate connection parameters for the desired database. For example:
<Call name="setInitParameter">
<Arg>APP_DB</Arg>
<Arg>jdbc:mysql:Server=MySQLServer;Port=3306;Database=mysql;User=user;Password=password</Arg>
</Call>
If Arc can successfully establish a connection with the APP_DB connection string, it will use that database as the application database.
External Java Server
When using the Java edition with an external Java servlet (any server other than the Jetty server that is included with the application), the details of configuring the application database depend upon the specific servlet used. Using the syntax appropriate for the specific servlet, one of the following approaches should be used when configuring the server:
- Define a JNDI datasource to include the connection properties for the target database.
- Set the APP_DB environment variable to a JDBC connection string.
If Arc can use the JDNI datasource or APP_DB connection string to connect to a database, it will use that database as the application database.