Installation on Tomcat

signoSign/Universal is developed in accordance with the servlet specification 3.0. In this section, we will explain installation of the application using the example of a Tomcat servlet container. For operation on other web servers (for example, a Wildfly), please see the documentation of the respective provider. It can also be run in a Docker container, for example.

Please also note that these instructions do not represent any best practice and that commissioning and support should be carried out by qualified persons. As the manufacturer of the web application, signotec accepts no liability for incorrect configurations of the IT infrastructure.

Required software

The software products listed below are absolutely essential for running signoSign/Universal. With the exception of the database server, all the software products must be installed on the host. If the database runs on another host, it must be accessible.

The following components are required:

• Java 8, 11, or 17

• Tomcat servlet container (8.5.x or 9.0.x)

• signoSignUniversal.war

• Database (e.g. MySQL)

Install Java

Install Java (see above) on your system. You can either download Java directly from the Oracle website or use OpenJDK under Linux.

Configure JAVA_HOME variable

Configure the “JAVA_HOME” environment variable. Under Windows, go to the advanced system settings (“Windows key + R” → “sysdm.cpl”). In the “Advanced” tab, you can configure a new variable using the “Environment variables...” button. To do this, click “New...” in the new window and enter “JAVA_HOME” as the name of the variable. The path must point to the installation directory of Java, e.g.:

C:\Program Files\Java\jdk1.8.0_XXX

Then click “OK” to confirm the entry and close the other windows.

Install Tomcat

Download the Tomcat “core” in one of the above-mentioned versions from the official Apache Tomcat website . Whether you want to use Tomcat as a ZIP or EXE (Windows Service Installer) is irrelevant for the operation of signoSign/Universal, so you can choose either option. For a quick installation, especially for testing, the ZIP package tends to be easier to use.

Java 11 patch

Since Java 11, some APIs are no longer included in Java Runtime and have to be inserted into the application by a patch. Information about the APIs that have been removed can be found here:

https://openjdk.java.net/jeps/320#Java-EE-modules

Content of the patch

The patch for using Java 11 is located in the “java11” folder of the delivery package. It contains the API specifications (webservices-api-[VERSION].jar) and the implementation of the APIs (webservices-rt-[VERSION].jar).

Alternatively, the files can be downloaded from Maven Central, for example:

• https://repo1.maven.org/maven2/org/glassfish/metro/webservices-api/[VERSION]

• https://repo1.maven.org/maven2/org/glassfish/metro/webservices-rt/[VERSION]

Application of the patch

The patch can be installed globally for all applications on the server, or for each individual application. If only signoSign/Universal is run on the server, we recommend the global installation.

Global installation

When the server starts, the files are loaded automatically and are available for all web applications. Copy the files into the “<TOMCAT-HOME>/lib/” folder for this purpose.

Custom installation

The patch is added to the libraries of the individual applications. To do this, open the file “signoSignUniversal.war” with a ZIP program and copy the files of the patch into the subfolder “WEB-INF/lib/.”

Create user

signoSign/Universal accesses the users of the web server by default. In the Tomcat example, the source for the created users can be defined in the “server.xml” in the “<TOMCAT-HOME>/conf/” folder. By default, Tomcat uses the file “tomcat-users.xml” in the folder “<TOMCAT-HOME>/conf/” as the user and role database.

Declare roles

signoSign/Universal supports two different roles. At least one of these roles must be declared.

In the following example, the user “john” is created with the password “password” and the role “ssu-user” in the “tomcat-users-xml”:

<!-- file conf/tomcat-users.xml -->
<tomcat-users>
  <role rolename="ssu-user"/>
  <user username="john" password="password" roles="ssu-user"/>
</tomcat-users>

It is possible to use existing authentication systems. The relevant data source and realm must be defined in Tomcat. You can obtain further information in the documentation of Tomcat Apache: https://tomcat.apache.org/tomcat-9.0-doc/realm-howto.html

TLS configuration (https)

The connection to signoSign/Universal via a secure HTTPS connection requires the corresponding configuration of the web server (Tomcat) or an upstream reverse proxy (or similar).

For more information on SSL and TLS configuration, please follow this link:

https://tomcat.apache.org/tomcat-9.0-doc/ssl-howto.html

Database

signoSign/Universal requires a database for version 3.13.0 and later. An H2 database (in-file) is used as standard. This database is only suitable for very simple applications and should generally only be used for test purposes. It is strongly recommended to use a managed database, such as MySQL. More information on configuring the database can be found in the “Configuring the database” section.

Configure application

To make server settings, simply edit the desired settings in “settings.properties,” which can be found under “signoSignUniversal.war/WEB-INF/classes.”

To make the settings update-safe, custom settings can also be defined as system or environment variables or an external configuration file can be created.

Deploy web application

After you have installed Java and Tomcat, place the “signoSignUniversal.war” from the download package in the /webapps/ directory of the Tomcat (<TOMCAT-HOME>/webapps).

Then start Tomcat via startup.bat (Linux: startup.sh) or the configured/installed service.

Call web resources

After Tomcat has started, you can call the following resources:

• Document Pool:
  http(s)://<DOMAIN>/signoSignUniversal/pool

• Showcase Demo:
  http(s)://<DOMAIN>/signoSignUniversal/documentation/showcase/index.html

• Swagger UI:
  http(s)://<DOMAIN>/signoSignUniversal/documentation/swagger-ui.jsp

• Technical documentation:
  http(s)://<DOMAIN>/signoSignUniversal/documentation/doc.xhtml

Troubleshooting

If Tomcat does not start, please check the following first:

• Was a compatible Java version used?

• Has the JAVA_HOME variable been configured correctly?

• Was a compatible Tomcat version used?

If Tomcat starts but it is not possible to log into the application, check the following:

• Have the user and role been configured correctly?

• Does the Tomcat service have the required rights to create the H2 database as a file / has the external database been connected correctly?