WAR Deployment


A WAR file, short for Web Application Archive, is a compressed package that contains all the vital resources and components of your web application. This format is designed for the purpose of deploying your web application onto a server.

A developer can generate a war file package of their application using two different approaches. The most straight-forward approach is to manually export a war file from Servoy Developer. For production scenarios, one can use the build automation pipelines of ServoyCloud to auto-generate war files from source, based on configurations and rules.

War deployment is the only way to deploy applications. The WAR file can be manually exported from Servoy Developer or it can be auto-generated from source using ServoyCloud. The WAR file can then be deployed on any J2EE standards compliant application server, like Glassfish, IBM WebSphere, Jetty or Apache Tomcat for example.

NOTE If you use a Servlet spec 5.0 container, like Tomcat 10, you need to use a Migration Tool to convert the generated WAR to the new specification. Because by default the generated WAR will not run and you will encounter errors like: java.lang.NoClassDefFoundError: javax/servlet/ServletContextListener. Use the migration tool for this or keep using a Servlet spec 4.0 variant like Tomcat 9.

Terminology In this chapter the term "application server" is used to refer to two different things:

  • Servoy Application Server: this refers to the specific libraries & software components created by Servoy that provide the Servoy specific functionality, like the Servoy Admin page, the hosting of Solutions that can be launched in the different types of Servoy Clients etc.

  • (J2EE standards compliant) application server: this refers to any Java application server that follows the J2EE server specification and under which the Servoy Application Server can run

NOTE NGClient needs the support of websockets and then the java implementation that is based on: JSR-356. For example Tomcat supports this from 7.0.43 and higher and Jetty from 9.1

Here is the webinar section that covers WAR deployment:



Deploying web applications using WAR (Web Application Archive) files offers several benefits:

  • Simplified Deployment: WAR files encapsulate the entire web application, including servlets, JSP pages, HTML files, and other resources. This simplifies the deployment process as you only need to deploy a single file.

  • Portability: WAR files are platform-independent and can be deployed on any Java application server that supports the Java EE standard. This portability allows for easy deployment across different server environments.

  • Easy Management: WAR files contain all the dependencies and configurations required for the web application. This makes it easier to manage and maintain the application as all components are packaged together.

  • Version Control: WAR files can be version-controlled using tools like Git, SVN, or other version control systems. This helps in tracking changes, rolling back to previous versions, and collaborating with team members.

  • Scalability: WAR deployment allows for easy scaling of web applications by deploying multiple instances of the same application on different servers or containers. This helps in handling increased traffic and load balancing.

  • Security: WAR files provide a secure way to deploy web applications as they can be digitally signed and verified to ensure the integrity and authenticity of the application.

  • Efficient Updates: Updating a web application deployed as a WAR file is straightforward. Simply replace the existing WAR file with the updated version, and the application will be redeployed with the new changes.

  • Resource Management: WAR files help in efficient resource management by packaging all the necessary resources in a structured manner. This reduces the chances of missing dependencies or configuration issues during deployment.

Overall, WAR deployment simplifies the process of deploying, managing, and scaling web applications, making it a preferred method for Java-based web development.

Database connections and .war deployment The needed database connections (including the repository server DB connection) have to be operational (so already started) before deploying the .war file.

If for some reason the .war deployment failed and you cannot access your solution/admin page as expected please check the J2EE server's log files as well as any relevant log files in [user_home_dir]/.servoy/server/[your_context_name]/... For example a repository version in the repository DB that is incompatible with the version of Servoy the .war was built on could generate this problem.

Generating a .war file

Exporting from Servoy Developer

  1. Do one of the following:

    1. Go to File > Export. A window will appear. In the tree, select Servoy > Export War File. Click on the Next button.

    2. Right click on the active solution in the Solution Explorer. Select Export Solution > War Export. A window will appear.

  2. Choose a name and a location for the export file. The name used for the export file automatically becomes the so-called "context" for the Servoy Application Server when installed on a application server, see About "context" for more info. You can use the options described below, then click Next.

    • Export NG1 resources: By default only Titanium Client will be exported

    • Include active solution and modules: A war export without a solution does not support newest features. Export the active solution and its modules.

    • Include some none-active solutions: You will be able to choose which ones later. It can be useful if you want your war deployment to include, for example, some batch processor solutions as well. If you check "Include active solution and modules", table changes and i18n, when selected, will be synced or imported into the application server when the WAR is first deployed. If the active solution has pre/post import hooks, those will be called during the import process. This solution (and its modules) won't be imported into the repository, but are serialized as a binary file that is read in from the file system every time the application/war is started. If that solution is also in the repository then that one will be deleted and will not be used. The repository is still needed for user and sequence management.

    • Export based on DBI files only: Exports the database meta data information for the main solution and the modules (if needed) using only table definitions. This method is used if at export the database is down (or has errors) so tables/servers are not accessible.

    • Export all tables from referenced servers: If checked, it will export all the tables for any server used in the solution. If it is unchecked, only tables that are actually used in the solution will be exported.

    • Export metadata from metadata tables: Based on workspace files

    • Check metadata for metadata tables: Compare metadata from workspace tot eh one from database for each table. (available if previous option is checked)

    • Export solution sample data:

      • Rows per table: default is 5000

      • All rows

    • Export i18n data

    • Insert new kyes only (don't update)

    • Export users: Exports the Servoy users specified in user and group security

      • Create nonexisting users and give existing users the permissions specified in import

      • Overwrite existing users completely (USE WITH CARE)

      • Allow users to be added to the Administrators permissions

  3. A list of all servers and database related import properties is shown. Data model changes are allowed for the selected servers. You can use the database related options described below, then click Next

    • Allow data model changes : If checked, it allows database structure in case the database structure on the server is different than the one in the export. e.g. table/columns changes or missing sequences. It is also possible to specify the server names for which data model changes are allowed.

    • Skip database view updates: If checked, it skips database view updates.

    • Allow sql keywords: It allows exporting tables which contain SQL keywords in table and column names. e.g. table having a column named “title”

    • Update sequences: If checked the sequences will be updated for the servers involved in the export, otherwise they will not be touched.

    • Override sequence types: The sequence types will be overridden for the exported servers.

    • Override default values: If checked, the default values will be overridden for the exported servers. This may break other solutions using the same tables, or cause tables to use nonexistent dbidentity or dbsequence sequences or other database auto enter types!

    • Overwrite repository permission security settings with import version: If checked, it overwrites the security settings for the groups which are exported and already present in the repository on the server.

  4. If "Include some none-active solutions" option was selected at step 2, a lsit of all none-active solutions will appear. You can select the solutions that you want to include in the WAR file, then click Next.

  5. Deploy configuration page is shown. Here you can specify the settings for the deployed war, then click Next

    • Add the given Tomcat context.xml file in the war file (META/-INF/context.xml) : browse and select the file location directory

    • Automatically upgrade repository if needed

    • Overwrite changed DB servers properties from previous deployment

    • Overwrite all Servoy properties

    • User home directory: select a directory. This must be a writable directory where Servoy application related files will be stored. If you leave empty, the system user home directory will be used.

  6. A list of all the plugins is shown. The plugins that will be used in the war can be left checked, the others can be omitted from the export.

  7. A list of all the beans is shown. The beans that will be used in the war can be left checked, the others can be omitted from the export.

  8. A list of all the jdbc drivers is shown. The drivers that will be used in the war and are not provided by the application server in which the war will be deployed can be left checked, the others can be omitted from the export.

  9. In the next dialog it is possible to choose which NG Components to export. The "exported components" list already contains the components required by the solution. However, in case the solution model is used to add components to forms/layouts, more components should be chosen from the "Available components" list.

  10. Similarly to the components dialog, the exported services can be chosen.

  11. Configuration settings for the default admin user are shown. Here you can specify default admin username and password, then click Next.

  12. Select a servoy properties file, log4j configuration file or xeb.xml to be used for the export.

    1. If no files are provided, a default file will be generated. An extra page will be spawned in the wizard, where a few settings need to be specified for the generated servoy properties file

    2. If a servoy properties file is specified, make sure the SocketFactory.tunnelConnectionMode on Network Settings page in Servoy Admin is set to http&socket. See WAR Deployment#About the servoy.properties file for more info.

  13. License key page is shown. Here you can enter the Servoy client license key(s), or leave empty for running the solution in trial mode, then click Next.

  14. A list of servers names is shown. Here you can select the database server names that will be used on the application server, then click Next.

  15. Database server configuration page is shown for each server name selected previously. Here you can specify the configuration for each database servers as it is used on the application server; the repository_server is required. Once all settings are done, click Finish.

Exporting multiply main solutions in one WAR.

If you use the option to export it with the active solution, only the active solution and its modules are exported as a runtime binary inside the WAR.

So other solutions that you have that are not in the module list are not exported. Currently there are 2 ways to also get those solutions in the WAR install:

  1. Export the other solutions are normal .servoy exports and import them through the admin page, this can be done for all solutions so you create the WAR without any runtime solution, but be sure then that it WAR has everything the NGClient solution(s) need. So all the component and ngclient services that are used by all the solutions.

  2. Create a wrapper solution around all the solutions and export that one as the active with its modules. (so the normal solution are the modules). Problem with this is that there can be conflicts between the solution because of the same form or scope names.

About "context"

A application server can host many applications, where a Servoy Application Server is just one of the applications. In order to be able to access each individual application and prevent name clashes, each individual application runs in it's own namespace or "context". If the application server runs on http://localhost:8080 and the context of an application is "xyz", the assets of the application are exposed through http://localhost:8080/xyz/.....

In case of a Servoy Application Server that is deployed as a WAR file with the name "myCustomServoyServer" on a application server on http://localhost:8080, the typical url's of the assets a Servoy Application Server exposes are:

  • http://locahost:8080/myCustomServoyServer/servoy-admin

About the servoy.properties file

The WAR export wizard in Servoy Developer allows the specification of a specific .properties file to be included in the WAR file. The settings in the .properties file that is specified will be included in the WAR export and when the WAR is deployed on an application server, the settings are applied. When the .properties file is not specified, the default settings for a Servoy Application Server will be included.

When updating an existing WAR deployment (see WAR Deployment#Updating a WAR deployment below for more info), only new default settings will be applied to the existing deployment, as to not override configuration changes made after the initial deployment.

On the application server, the settings are stored in the following location: {user.home}/.servoy/server/{context}/servoy_server.properties.

If {user.home} is a read-only folder, then a SERVOY_USER_HOME system variable (or in 2019.03 this can also be a Environment variable) must be defined to point to a writable folder. You can give this directly to the JVM as well using -DSERVOY_USER_HOME=... (in case of Tomcat you can put this in JAVA_OPTS; see Tomcat documentation on how that can be changed). Starting from Servoy version 8.2, it is also possible to set this in the servoy.properties file used for the WAR export, by setting "servoy.user.home". If this 'servoy.user.home' is used in the properties file then property substitution (system properties or environment variables value replacement) is not supported. This value must be a valid folder by itself, use the SERVOY_USER_HOME system property or since 2019.0 that same property can also be set as an environment variable.

NOTE when using an existing servoy.properties file, check if the property "SocketFactory.tunnelConnectionMode" is set to one of the following values: "Http&Socket", "Http" or "Socket". The "2waysocket" option is not fully supported when deploying using a WAR: deploying multiple Servoy WAR's on the same server or a hot redeploy does not work when using "2waysocket". When not using an existing servoy.properties file the "SocketFactory.tunnelConnectionMode" is set to "Http&Socket".

NOTE When you want the location of the leading properties file of a war/server deployment: The default admin homepage tells you the full path under the Server Information section: Settings file for this server: xxxxxxx

NGClient grouping/minizing

When exporting a war the exporter will group all css and js files through a few urls, these urls that are created are unique for this WAR instance. Servoy will send caching headers on those urls that will let the browser and proxies know that they can be cached "forever". This way the browser doesn't have to redownload those resources when hit again.

The grouping tries to use the minimized version of they are there on the file system. So a component or service can have libs that are the normal js files for easier debugging in the developer, but besides it it can have the same js name but ending on *.min.js. Those will be taken by the grouper, this way the download is even way less smaller. All other files can by minimized by Servoy on export, but this is a very simple minimizer.

All the templates of the components that are inside the war are also grouped in 1 big js file, that is again grouped. So all the template files are also immediately available in the browser without the need to download them one by one.

If for some reason a component doesn't work in grouping mode then you can turn this use of the generated grouping files off at the admin page: servoy.ngclient.enableWebResourceOptimizer set that to false. Better is to improve the component itself to let the Servoy grouper know that it should exclude this component or 1 of its support libs. For this the spec has a few options, the libraries section can have a "group":false besides name/url/version and the spec itself can have also that same property. See Specification (.spec file).

ServoyCloud Pipelines

When using ServoyCloud Pipelines, you can configure a build job to auto generate the war file for you. The result of a build job will be a package containing the war file.

ServoyCloud approach offers a more streamlined and automated process. ServoyCloud simplifies the deployment and management of applications by providing a platform that handles all the necessary configurations and updates. This saves time and reduces the risk of errors that can occur with manual processes. Additionally, ServoyCloud offers scalability, reliability, and security features that may not be easily achievable with a manual approach. Overall, using ServoyCloud for war file export can improve efficiency and ensure a smoother deployment process.

Deploying a .war File

War deployment allows packaging a web application with all its dependencies into a single web archive (WAR) file, which can then be deployed on any standard Java application server like Apache Tomcat or Jetty. This simplifies deployment, enables running multiple versions of the same application, and integrates with enterprise infrastructure.

War file deployment eliminates the need for server downtime during updates, streamlines dependency management, and supports running different versions of applications simultaneously.

Deploying a WAR file depends on the application server used. Some application servers host an admin webpage to manage WAR deployments. On other application servers the deployment can be as simple as placing the WAR file in a special 'webapps' folder of the web server, after which the WAR automatically gets deployed by the application server. For details see the documentation of the application server used.

Some application servers automatically expand the WAR file, which means that the content of the WAR file is automatically unzipped into separate files/directories in the appropriate directory of the application server.

When running multiple Servoy Application Servers through WAR deployment on the same application server it is vital to make sure each Servoy Application Server is configured to use a different RMI port and use a different set of databases

Port conflicts If you keep your developer open while testing war deployment on the same machine, please take care of possible port conflicts. For example if your J2EE server is Tomcat it will probably try to use 8080 which is already being used by Servoy Developer. So you will not be able to access it from the browser on that port. Just close developer before deploying or change the ports (see your J2EE server's documentation or this topic if it is not Tomcat) on one of the servers.



Setting up Apache Tomcat involves several steps, including downloading and installing the Tomcat server, configuring it, and deploying web applications. Here is an overview of the Tomcat setup process:

  1. Download Tomcat: Visit the Apache Tomcat website and download the latest version of the Tomcat server that matches your operating system.

  2. Install Tomcat: Run the installer and follow the on-screen instructions to install Tomcat on your system. Choose the installation directory and configure any additional settings as needed.

  3. Configure Tomcat: After installation, you may need to configure Tomcat by editing configuration files like server.xml and web.xml. These files contain settings related to ports, security, and other server configurations.

  4. Deploy Web Applications: To deploy a web application, create a WAR file containing your application files and deploy it to the Tomcat server. You can deploy applications using the Tomcat Manager web application or by manually copying the WAR file to the webapps directory.

  5. Start Tomcat: Start the Tomcat server either through the command line or using the provided scripts. You can access the Tomcat Manager web interface to manage deployed applications and monitor server status.

  6. Access Web Applications: Once Tomcat is running, you can access your deployed web applications by entering the appropriate URL in a web browser. The default port for Tomcat is usually 8080, so you can access the Tomcat Manager at http://localhost:8080 and deployed applications at http://localhost:8080/application-name.

  7. Troubleshooting: If you encounter any issues during setup or deployment, refer to the Tomcat logs located in the logs directory for error messages and debugging information.

By following these steps, you can set up and configure Apache Tomcat for deploying and running Java-based web applications.

Deploying a .WAR file on Apache Tomcat

Deploying a WAR (Web Application Archive) file on Apache Tomcat involves several steps. Here is a guide on how to deploy a WAR file to Tomcat:

  1. Create a WAR File: First, create a WAR file that contains your web application files, including servlets, JSP pages, HTML files, CSS, JavaScript, and other resources.

  2. Access Tomcat Manager: Open a web browser and navigate to the Tomcat Manager web interface. The URL is usually http://localhost:8080/manager/html.

  3. Login to Tomcat Manager: Enter your Tomcat Manager credentials to log in. If you don't have the credentials, you may need to set them up in the Tomcat configuration files.

  4. Deploy the WAR File: In the Tomcat Manager interface, scroll down to the "WAR file to deploy" section. Click on the "Choose File" or "Browse" button to select the WAR file from your local system.

  5. Deploy the Application: After selecting the WAR file, click on the "Deploy" button to start the deployment process. Tomcat will upload the WAR file and deploy the web application.

  6. Monitor Deployment: Tomcat will display the deployment progress and provide feedback on whether the deployment was successful or if there were any errors.

  7. Access the Deployed Application: Once the deployment is complete, you can access the deployed web application by entering the application's URL in a web browser. The URL typically follows the format http://localhost:8080/application-name.

  8. Test the Application: Verify that the deployed application is running correctly by interacting with its features and functionalities.

By following these steps, you can successfully deploy a WAR file to Apache Tomcat and make your web application accessible through the Tomcat server.

Updating an existing WAR deployment

A deployed WAR file can't be modified. Therefor the ability of a Servoy Application Server to upload new (versions of) plugins, beans, drivers and LAF's is disabled.

If updates are required to plugins, beans, drivers, or Servoy Application Server version updates, a new WAR export needs to be made from Servoy Developer. The generated WAR file can then be deployed using the WAR deployment mechanism that most application server have to upload WAR files and (re)deploy them.

When upgrading an existing WAR deployment, make sure to use the exact same context, otherwise when the WAR file gets deployed, it doesn't update the existing deployment, but instead deploys the WAR as a new application under the new context.

Last updated