This guide explains how to create a production version of the LuciadFusion Platform, and how to deploy it.

Deployment architecture

The LuciadFusion Platform is a server application that provides access to published data. The server application is accessed through a client application communicating over the network. The client application can be a desktop application or a browser-based application.

FusionPlatformDeployment
Figure 1. LuciadFusion Platform deployment

Client applications can communicate directly with the server application. However, it is recommended to integrate the server application behind a web server, such as Apache HTTP Server, with a reverse proxy setup. Many organizations currently have such a setup in place. It makes the configuration of secured connections to the server easier.

In a reverse proxy setup, direct access to the server by client applications is blocked. The client application uses HTTPS to connect to the reverse proxy server. The reverse proxy server forwards the requests to the LuciadFusion server using plain HTTP, on an internal network. The SSL certificates are managed by the reverse proxy server, the Apache HTTP Server.

DeploymentRecommended
Figure 2. Recommended LuciadFusion Platform deployment

Preparing the LuciadFusion server for deployment

The LuciadFusion distribution comes with a deployment build script. Before you can run it, you need to complete a few tasks as preparation.

Setting up the build environment

The build environment prerequisites for deploying with the deployment build script are ProGuard and Ant.

You can choose to obfuscate the LuciadFusion code when you deploy it. The deployment build script includes obfuscation with ProGuard as a deployment step. The obfuscation tool ProGuard is not re-distributed within the LuciadFusion distribution. Please install ProGuard by following the instructions in this article.

A sample configuration script for this tool, specific to the obfuscation of the LuciadFusion server, is available in build/proguard/luciad_fusionplatform_service.pro. See the Obfuscation section on the Technical Notes page of the product browser documentation for more information about obfuscation.

The deployment build script itself is based on Ant. The Ant tool is available within the distribution. No extra steps are needed to set it up.

Due to a bug in ProGuard, the ProGuard 7.0.x versions do not include ant support. Either use a different version of ProGuard or download the ProGuard ant jar yourself.

If deployment size is an issue, you can reduce the deployment package size by approximately 200 MB by excluding the resource jar containing geoid metadata. See the commented out exclude attribute in the obfuscate target within build/fusionplatform/deploy_fusionplatform_service.xml.

Installing your deployment license

The LuciadFusion requires a deployment license. Copy your deployment license jar deployment.jar to the licenses folder. It is picked up by the build script and included in the generated artifact.

Selecting and installing a database

The LuciadFusion product stores its configuration in a database. PostgreSQL, Oracle, SQL Server and H2 are supported.

In a production environment, a PostgreSQL, Oracle or SQL Server database is strongly recommended.

PostgreSQL

For PostgreSQL, see https://www.postgresql.org/ for download and installation instructions. The PostgreSQL user that is initially configured to create the LuciadFusion tables requires the following privileges:

  • LOGIN

  • INHERIT

Make sure to enable the POSTGIS and PGCRYPTO extensions.

Oracle

For Oracle, see https://www.oracle.com/database/ for download and installation instructions. The Oracle user that is initially configured to create the LuciadFusion tables requires the following privileges:

  • CREATE SESSION

  • CONNECT

  • CREATE TABLE

  • CREATE VIEW

  • CREATE SEQUENCE

  • CREATE INDEXTYPE

  • UNLIMITED TABLESPACE

  • CREATE TRIGGER (this is only for 11g)

The "Spatial and Graph" module needs to be installed. See https://www.oracle.com/database/technologies/spatialandgraph.html.

SQL Server

For SQL Server, see https://www.microsoft.com/en-us/sql-server/default.aspx for download and installation instructions.

The SQL Server database created for LuciadFusion needs to turn the READ_COMMITTED_SNAPSHOT option to true.

The user that is initially configured to create the LuciadFusion tables in that database needs the db_owner role for that database.

Configuring the application

The LuciadFusion distribution comes with a sample setup that uses a fusion.development profile. For deployment, you must prepare a fusion.production profile by modifying the configuration files. They are located in the folder config.

Copy the file application-fusion.production-template.yml to application-fusion.production.yml.

Modify the properties to match your environment. The documentation for the properties is in the file itself. You can also add more profile configurations to the fusion.development and fusion.production profiles. For guidelines regarding the configuration files, see Configuring LuciadFusion Studio.

Adding custom code

This is an optional step. The LuciadFusion distribution is organized in such a way that you can make a deployment-ready version of the application without writing custom code.

The Studio customization and Platform Extension documentation explain how you can plug custom code into the LuciadFusion server application.

The build script below picks up source code located in the directory src. Copy your custom source files in this folder if you want to include them. Additionally, if your custom code contains Spring annotations or code that requires Java reflection to discover, make sure that you exclude your custom code from obfuscation (see build/proguard/luciad_fusionplatform_service.pro which contains a commented out example).

Adding LuciadFusion Studio UI translations

The LuciadFusion distribution offers the UI of the end user application LuciadFusion Studio in English. However, it is organized in such a way that you can easily add UI translations.

How to localize the LuciadFusion Studio UI explains how you can add Studio translations.

The build script picks up the translations located in config/studio/static/i18n/translations directory.

Build the LuciadFusion server application for deployment

Go to the folder build/fusionplatform and run the deployment build script deploy_fusionplatform_service for your platform:

  • Windows: deploy_fusionplatform_service.bat

  • Linux and macOS: deploy_fusionplatform_service.sh

The deployment build generates two artifacts in the directory distrib/FusionPlatform.

Running the example script for a deployment build provides more information about the build script and Selecting the right build artifact helps you choose between the artifacts.

Running the example script for a deployment build

The build script in the distribution is an example Ant build script that shows how to generate a LuciadFusion server application with a production profile. The configuration for the production profile is explained in Configuring LuciadFusion Studio. In this section, it is assumed that the configuration has been prepared.

The build script provides targets to build LuciadFusion for deployment within a servlet container, Apache Tomcat or Jetty for example, and as a standalone deployment within an embedded servlet container.

You can run the deployment build script without arguments. The default target generates two artifacts, a WAR and a standalone zip archive for example. If you want to control what artifact type is generated, you must specify one of the following build targets as a command line argument.

  • package:zip: builds the application in such a way that you can start it up as a standalone application using a start script. The application is packaged in a ZIP archive.

  • package:war: builds the application in such a way that you can deploy it in a servlet container like Apache Tomcat or Jetty. The application is packaged as a WAR.

  • package: the main build target of the example build script. It generates both the WAR and the ZIP archive.

The deployment build script contains comments that help you create your own automated deployment build process. The build script generates output on the console for your convenience.

Selecting the right build artifact

You need to choose the artifact depending on your deployment options.

  • To deploy in a servlet container, Apache Tomcat for example, use LuciadFusionPlatform.war, a web archive ready for deployment. The requirement for the servlet container is that it must support the servlet 3.1 specification. If you deploy in a default configuration of Apache Tomcat, you can start using the LuciadFusion Studio web application for configuration of the server. You can find it at the location http://localhost:8080/LuciadFusionPlatform/studio. The web archive artifact will be needed in the majority of the cases.

When using Apache Tomcat 10, please note that LuciadFusionPlatform.war needs to be put in the webapps-javaee folder instead of in the webapps folder used in prior versions. This is because the Java EE platform has been evolved into the Jakarta EE platform; as of Apache Tomcat 10, Jakarta EE applications need to be put in the webapps folder, whereas Java EE applications such as LuciadFusion need to be put in the webapps-javaee.

  • To deploy the server application in a standalone version, use LuciadFusionPlatform.zip. It offers a start-up script using an embedded Jetty servlet container. Extract the zip archive and start the LuciadFusion Platform server by running the script StartFusionPlatformServer. The Studio web application to configure the server is available at the location http://localhost:8080/studio. This artifact is useful mainly for local deployment.
    This option allows you to still fine-tune the configuration (application-fusion.production.yml) in the resources directory, if necessary. Changes come into effect when the application is restarted.