After the upgrade - Configure the front-end web server (reverse proxy/load balancer)

This chapter provides information about how you need to configure the portal properties in Intrexx so that your portal can be accessed via a browser. This particularly relates to the connection between the "embedded Tomcat" and the front-end web server (reverse proxy) you are using. The configuration settings described in this chapter need to be made after both a new installation and an upgrade from Version 18.03 to 20.09.

Internet Informations Service (Windows)

A. Upgrade from Intrexx 18.03 to Intrexx 20.09

After you have upgraded Intrexx, you need to reconfigure the properties of your portal. Due to the modified architecture as of Intrexx 19.03, the edit fields in the portal properties have been changed accordingly.

18.03
20.09

Please note: Virtual directories are not supported from Intrexx 19.03 onwards.
If you used virtual directories in Intrexx 18.03, then you need to create a website in IIS for each virtual directory. A detailed guide to websietes in IIS is available in the chapter Add website in IIS.

B. Upgrade from Intrexx 19.03 and later to Intrexx 20.09
The dialog for configuring the front-end web server has been changed in Intrexx 20.09. Entries from Intrexx 19.03 are transferred automatically.

19.03
20.09


Step-by-step guide

To configure the front-end web server in Intrexx 20.09, please proceed as follows:
  1. Start the Portal Manager.
  2. Log in to your portal.
  3. Open the portal properties ("Portal" menu > "Portal properties").
    This will open the "Edit portal" dialog.
  4. Click on the menu item "Front-end web server (reverse proxy / load balancer)".



    Name Description
    Type Select "Internet Information Services" (IIS) here.
    IIS Website Select the website that you added to IIS for your portal earlier. Do not use the "Default Web Site" from IIS.

    Embedded Tomcat port The port that you used in Intrexx 18.03 will be shown here. You can leave this port as it is.
    Please note: The port 1337 is predefined for a new installation.
    Base URL of the portal The base URL needs to be entered here.
    The first part refers to the protocol. Please make sure that "https" is specified. The second part is made up of the hostname that you defined in IIS. Please make sure that this ends with a slash (/). It is essential that this is correct so that your portal can be accessed in the browser.
  5. Click on "OK". You have now configured the front-end web server in Intrexx 20.09.
    You may need to restart the Intrexx portal services after making your changes. (Open the Windows "Services" app and restart the Intrexx portal service there.)
    Open the respective portal in the browser to test whether the portal properties have been configured correctly and the upgrade was successful.

    Please note: Some functions need to be checked in general after upgrading to Intrexx 20.09. These include the correct appearance of portlets, for example.

NGINX (Linux)

A. Upgrade von Intrexx 18.03 auf Intrexx 20.09
After you have upgraded Intrexx, you need to reconfigure the properties of your portal. Due to the modified architecture as of Intrexx 19.03, the edit fields in the portal properties have been changed accordingly.
18.03
In Intrexx 18.03, it was not possible to select NGINX as the web server type or reverse proxy.



20.09
Intrexx 20.09 has the menu item "Front-end web server (reverse proxy / load balancer)".
You can configure the settings for the connection to NGINX.

B. Upgrade from Intrexx 19.03 and later to Intrexx 20.09
The dialog for configuring the front-end web server has been changed in Intrexx 20.09. Entries from Intrexx 19.03 are transferred automatically.
19.03


20.09
Intrexx 20.09 has the menu item "Front-end web server (reverse proxy / load balancer)".
You can configure the settings for the connection to NGINX.

Step-by-step guide

To configure the front-end web server in Intrexx 20.03, please proceed as follows:
  1. Start the Portal Manager as the Administrator.
  2. Log in to your portal.
  3. Open the portal properties ("Portal" menu > "Portal properties").
    This will open the "Edit portal" dialog.
  4. Select the menu item "Front-end web server (reverse proxy / load balancer)" "Frontend Webserver (Reverse Proxy / Loadbalancer)".



    Name Description
    Type Select "NGINX" here.
    NGINX virtual host "NGINX virtual host" refers to the embedded Tomcat. NGINX connects to the Intrexx portal service via the virtual host. Typically, "localhost" should be entered here. (One exception to this is when NGINX is installed on a different server to Intrexx.)
    NGINX configuration file You can generate the NGINX configuration file with Intrexx.

    Enter the path to the directory that the NGINX configuration file should be generated in.
    Example: "/myfolder/portal.example.org.conf"
    Afterwards, copy and link the NGINX configuration file to the desired folder within "/etc/nginx".
    Example: "/etc/nginx/sites-available/ portal.example.org.conf"
    Embedded Tomcat port The port that you used in Intrexx 18.03 will be shown here. You can leave this port as it is.
    Please note: The port 1337 is predefined for a new installation.
    Base URL of the portal The base URL needs to be entered here.
    The first part refers to the protocol. Please make sure that "https" is specified. The second part is made up of the hostname that you defined in the NGINX configuration file. Please make sure that this ends with a slash (/). It is essential that this is correct so that your portal can be accessed in the browser.

  5. Click on "OK". You have now configured the front-end web server in Intrexx 20.09.
    You may need to restart the Intrexx portal services after making your changes.
    Open the respective portal in the browser to test whether the portal properties have been configured correctly and the upgrade was successful.

    Please note: Some functions need to be checked in general after upgrading to Intrexx 20.09. These include the correct appearance of portlets, for example.

No front-end web server

Usually, a front-end web server (reverse proxy) is used in conjunction with Intrexx. In most cases, this is usually IIS from Microsoft or NGINX.
There are numerous reasons to recommend using a reverse proxy. In particular, a reverse proxy allows you to use the existing Windows authentication for accessing the portal.
In principle, you can access a portal without a front-end web server (reverse proxy). However, this can only be recommended for test and development portals.

Step-by-step guide

To not use a front-end web server for your portal, please proceed as follows:
  1. Start the Portal Manager as the Administrator.
  2. Log in to your portal.
  3. Open the portal properties ("Portal" menu > "Portal properties").
    This will open the "Edit portal" dialog.
  4. Select the menu item "Front-end web server (reverse proxy / load balancer)" "Frontend Webserver (Reverse Proxy / Loadbalancer)".



    Name Description
    Type Select "No front-end web server" here.
    Embedded Tomcat port Enter the port used to address the embedded Tomcat. This is usually port 1337.
    Encryption (HTTPS) Activate this checkbox if you would like to encrypt communications between the embedded Tomcat and the browser.
    Self-signed certificate for "localhost" Select this option if communications between the embedded Tomcat and the browser should be encrypted using a self-signed certificate (for test and development portals).
    In this case, Intrexx automatically generates a self-signed certificate and uses it for the encrypted connection.
    Use the following certificate Select this option if you have a certificate.
    Normally, this certificate needs to be saved in a certificate store that you have manually created in advance. (The certificate used here is therefore not saved in the certificate store of your portal.)
    Certificate file Click on the icon to search for the certificate.
    Certificate type Select the type of certificate store (keystore) that the certificate is saved in.
    Keystore password Enter the password for the keystore that the certificate is saved in.
    Certificate key password Enter the password for the certificate (certificate file).
    Please note: The password for the keystore and certificate store are often identical.
    Base URL of the portal The base URL needs to be entered here.
    The first part refers to the protocol. Please make sure that "https" is specified. Please make sure that this ends with a slash (/). It is essential that this is correct so that your portal can be accessed in the browser.
  5. Click on "OK".
    You have now configured your portal without a front-end web server (reverse proxy).

Manual setup

Select "Manual configuration" as the type if you would like to manually configure communications between embedded Tomcat and the browser.
In doing so, you forgo the dialog-supported configuration that is available for the "Internet Information Services (IIS)", "NGINX" and "No front-end web server" options.



Name Description
Base URL of the portal The base URL needs to be entered here.
The first part refers to the protocol. Please make sure that "https" is specified. Please make sure that this ends with a slash (/). It is essential that this is correct so that your portal can be accessed in the browser.

Perform checks

Check the availability of the portal

Can the portal be opened in the Manager?

If not, please check whether the portal services have been started first. Check the following Intrexx services: Portal services, Solr service and possibly the Supervisor service. If the services have not been started automatically, start them now.

If you cannot start the services, please check the respective logfile (Portal.log or Portal_startup.log) to see if errors are listed at the attempted start time. If this is the case, contact United Planet support. If the services are running but the portal is still not available, please note that installed security systems like firewalls need to be configured accordingly to be able to establish the connection between a Portal Manager (potentially on a client PC) and the Intrexx server.

Knowledge Base Article No. 2407: Network and Internet Connections | Firewall Configuration and Information

Can the portal be opened in a browser?

  1. If not, access the portal in a browser directly on the server to begin with. If there are problems here as well, check the configuration of your web server as described here. If you need any help here, please contact United Planet support.
  2. What to do if the portal can be opened but authentication fails:
    • Please test whether the Intrexx authentication is functional
    • Please test whether it is possible to access the portal after reconfiguring the chosen authentication and restarting the portal.
Knowledge Base Article No. 3259: Troubleshooting - User authentication | Windows authentication with IIS
Knowledge Base Article No. 3335: Custom ("Other") authentication method with Intrexx 19.03

Adjust the portal pages

  1. As mentioned above, portal pages need to be adjusted to the new framework. The new portlet framework is now a responsive grid that portlets can be positioned in. The portlets already in use are available after the update but the order, positioning and width may have changed. Start by configuring the grid so that you can position the portlets as needed. You also have the ability to optimize the grid for tablets and mobile devices at this point. You can move the portlets within the grid via drag & drop.
  2. On application portal pages, it may be the case that parameters or values from the request, etc. are not available in the portlet, which then causes errors. The update process tries to take over all known possibilities for you but we have seen that this cannot always work reliably as the possibilities are too diverse. If errors occur in individual portlets, start by checking whether all required parameters are transferred from the portlet container to the portlets.

Check the applications

  1. Once your portal is rolled out, you should check the logfiles regularly in the following days. This includes the portal.log file. This logfile provides an overview of problems in your applications. If this is the case, please contact your partner or the United Planet support as needed.
  2. If there are problems in your applications, you should definitely check if JavaScript or Velocity script, which may need to be adjusted as described here, is used in these applications. Even though United Planet takes great caution at this point, it may be the case that a required adjustment is missing from this document. Furthermore, it may well be that a function should have already been adjusted during a previous update. Please check the update document for Version 18.03 in this case - or even earlier versions. If in doubt, please contact our support team - they will provide you with the assistance needed.

Check the processes

Once your portal is rolled out, you should check the logfiles regularly in the following days. This includes the workflow.log file. This logfile provides an overview of problems in your processes. If this is the case, please contact your partner or the United Planet support as needed.

Check the search server (Solr)

Click on Manage cores/collections to check whether all cores and collections can be assembled. You should see a green checkmark next to each core in the list. The cores need to be reconfigured otherwise.

Knowledge Base Article No. 3102: Solr | Reconfigure search configurations and cores/collections

Check the server load

Since the introduction of the Solr search server (Intrexx 8.0 or higher), it is not atypical for an Intrexx server to use up more resources than previous Intrexx versions. Equally, the functions and features of Intrexx have changed significantly. Whereas older, simpler portals could be all means be run with less than 1GB memory and a dual-core processor, the server requirements are considerably higher now.

Knowledge Base Article No. 3326: Large consumption of resources like CPU, RAM and HDD | Performance

Errors in Patch.log: Cause, possible corrective actions and subsequent steps

As soon as there is a reference, the app cannot be published.
ERROR 2019-08-30T08:34:12,317Z - de.uplanet.lucy.server.patch.FinishPortalPatcher[main]
Failed to add views to user applications.
de.uplanet.jdbc.StandardDbException: Error: 2627, SQLState: 23000: Violation of PRIMARY KEY constraint 'PK__LCAPPDG__0EF23BF8383528AF'. Cannot insert duplicate key in object 'dbo.LCAPPDG'. The duplicate key value is (DAF7CECF66481FCABE50E529828116EAFE906962).
    at de.uplanet.jdbc.sqlserver.SQLServerDescriptor.convertException(Unknown Source) ~[ix-server-common.jar:9.2.0.20190823.199961]
    at de.uplanet.jdbc.JdbcPreparedStatementImpl.executeUpdate(Unknown Source) ~[ix-server-common.jar:9.2.0.20190823.199961]
    at de.uplanet.lucy.server.businesslogic.adminapp.publish.user.UserApplicationSchemaPublisher.a(Unknown Source) ~[ix-server.jar:9.2.0.20190823.199961]
...
Solution: Search for the field in the Users application and remove the reference. Most references are shown in the Problems area. Existing references may be shown when publishing.

Errors in PublishAllApplication.log: Cause, possible corrective actions and subsequent steps

Error when validating the schema of one or more applications

  1. Identification

    Intrexx applications are XML files. These files contain all elements that belong to an application: Data groups, data fields, pages, edit and view elements, texts and much more. From Intrexx 19.03 onwards, the structures of this type of XML file is monitored exactly to ensure the validity of an application in the future. From a very large pool of applications, United Planet has created an almost complete picture of all possibilities and ensures this accordingly with so-called schema validation. However, if there are applications in your portal, whose XML structure has been adjusted for whatever reason, this can mean that the corresponding applications cannot be published until the schema violation is removed. A schema violation can be identified in the logfile by looking for the following pattern:
    XML: B0128D0439003C858896C4E3F0A564DEB305CB74.xml
    Cause:<radiocontrolgroup...><simplegroup dynamic-width = 'false' fixedpos = 'false' guid = '8489B4BC5F0448D60F284252D17E01FE9B01D0F9' html-structure = 'table' isNewControl = 'true' level = '1' name = 'simplegroup5504ADF6' rect = '0,0,140,60'>
    cvc-complex-type.2.4.a: Invalid content was found starting with element '{"http://schemas.unitedplanet.de/intrexx/2016/application/element/":simplegroup}'. One of '{"http://schemas.unitedplanet.de/intrexx/2016/application/element/":defaultvalue, "http://schemas.unitedplanet.de/intrexx/2016/application/element/":radiocontrol}' is expected.
    
  2. Consequences

    If it concerns an isolated application, which has no dependencies on other applications, then portal can by all means be operable - however, this specific application cannot be published and not accessed as a result. If there are dependencies to other applications, these also cannot be published as a result and it may mean that it is not possible to use your portal at all.
  3. Measures

    If you find this kind of error in your logfile, please contact our support. We can work together to try and remove the error either directly or by creating a patch with the assistance of our Development department; this patch not only helps you but also all other potential portals that are affected by this error. Please note that this solution can typically only be implemented with a later online update.

Troubleshooting

Port is already in use

Check the port allocation. A portal can only be accessed when it is accessible via the default port 443 (for HTTPS). When setting up the ARR module in the IIS, this connection is defined accordingly. If this port is already in use from a different software product or set-up website, then a connection to the portal is not possible. To check whether another product is using the port, proceed as follows:
  1. Open the command line.
  2. Enter the command
    c:\> netstat –anop tcp
  3. If you receive an entry in the format
    Local Address: "0.0.0.0:443"  State:"LISTENING"
    then you know that the port is already in use. To find out which program is using this port, you need to search for the process with a suitable tool (e.g. Process Explorer from Sysinternals). This process is stated in the PID column in the results of the netstat command.

Embedded Tomcat configuration: HTTP Error 400 - Request Header is too large

Problem The error message "HTTP Error 400 - Request Header is too large" is sometimes shown if the portal is being run with Windows SSO authentication and a user is a member in a lot of Active Directory groups.

Solution Increase the value for the parameter "maxHttpHeaderSize" to "65536".
You can find the parameter "maxHttpHeaderSize" in the file "server.xml" in the directory "Installationsverzeichnis\portalname\tomcat\conf"

Windows authentication: Tomcat filter not yet activated

To use Windows authentication in the portal as well as for Single Sign On for the connectors, a filter must be activated in the web.xml file. This can be found in the portal directory external/htmlroot/WEB-INF. This filter is usually activated automatically as soon as Windows authentication has been activated.
  1. Open the file with a suitable editor (e.g. Notepad++)
  2. Search for the term "External Authentication Filter".
    <filter-name>External Authentication Filter</filter-name>
            <filter-class>de.uplanet.lucy.server.connector.servlet.ExternalAuthenticationFilter</filter-class>
            <init-param>
                <description>
                    This property is used to enable or disable the filter.
                    IMPORTANT: For compatibility reasons the default value of this property
                    is true for the External Authentication Filter.
                    Values: true (default) or false.
                </description>
                <param-name>enabled</param-name>
                <param-value>false</param-value> 
            </init-param>
    		
  3. Modify the line
    <param-value>false</param-value>
    to
    <param-value>true</param-value>
  4. Save the file.
  5. Restart the portal service.

Kerberos authentication for connectors: Tomcat filter not yet activated

When using connectors with the Kerberos authentication, an additional filter is required that in some cases needs to be added to the web.xml file manually like in the step above:
  1. Open the file with a suitable editor (e.g. Notepad++)
  2. Search for the term "connector.portalserver.additionalHeaders"
    <init-param>
    	<param-name>connector.portalserver.additionalHeaders</param-name>
    	<param-value>X-Header-1 X-Header-2</param-value>
    </init-param>
  3. Copy the entire entry into the subsequent, not-commented-out area. Edit the entry as follows:
    <init-param>
    	<param-name>connector.portalserver.additionalHeaders</param-name>
    	<param-value>X-AccountName X-KrbTicket</param-value>
    </init-param>
  4. Remove the characters "--" at </filter-mapping-->
  5. Save the file.
  6. Restart the portal service.