Starting the FirstSpirit applications

After the installation please enter the following URL (example call – host name and domain has to be changed to your settings):

http://[hostname].[domain].[tld]:[port]

A standard installation uses port 8000. If port 8000 has been already preallocated by another application before the installation of the FirstSpirit Server, FirstSpirit selected automatically another free port during installation. The port number to be used for the URL is listed as parameter HTTP_PORT in the configuration file ~FS/conf/fs-server.conf.

The standard connection to the FirstSpirit Server is established according to the settings for installation. If connection was successful, a login dialog is displayed.

For information about the runlevel see Unix (→Documentation for Administrators).

If errors occur while the login window or the FirstSpirit start page is displayed, check whether the HTTP port on the server side is already occupied. The same applies when starting in socket mode. It is important to check the port configuration on the server side here too.

 The configuration of FirstSpirit (e.g. port configuration) takes place via configuration files located in the installation directory of the FirstSpirit Server. File structure and configuration possibilities are described in the FirstSpirit Server (fs-server.conf) (→Documentation for Administrators)).

FirstSpirit login dialog

The user can log in at the FirstSpirit Server via the login dialog. This login is valid for all applications on the server and also lasts for inactive users for a certain period of time.

During the first login process as server administrator, the user has to log in at the FirstSpirit Server via the standard login.

Please enter “Admin” for both user name and password for the login as server administrator. Please observe that both words start with a capital letter. The Login button is only active if at least one character has been entered in both fields. Click on this button to open the FirstSpirit start page. The logged-in user “Admin” is displayed at the top of the start page.

During the next step, it is recommended to change the standard password for the server administrator. This is possible under the menu item Change password in the area User.

FirstSpirit Startpage

You can access all FirstSpirit applications via the start page.

See FirstSpirit start page (→Documentation for Administrators).

FirstSpirit Launcher

The FirstSpirit Launcher provides its own (configurable) Java environment for FirstSpirit contexts. This enables the SiteArchitect and ServerManager to run in a preconfigured environment that is independent from the Java version present (or even absent) on the client machine.

Advantages:

+ Security: Java (Web Start) support is no longer required in the web browser. This eliminates a potential security vulnerability in terms of outside attacks.

+ Update: The amount of administration and maintenance work is significantly reduced because no Java Environment is installed on the workstations and so they no longer have to undergo regular Java updates. The Java version of the Launcher is now updated automatically as part of the FirstSpirit server update process.

+ Compatibility: The Java version used within the Launcher is selected and extensively tested by Crownpeak. As a result, it is possible to prevent the use of Java versions that have already been identified as problematic. Another positive aspect of the Launcher is that it eliminates the possibility of incompatibilities or version conflicts with other Java products that are installed on the system.

+ Usability: The launcher offers a convenient tray application, which offers an easy to handle overview off running and recently used FirstSpirit Java applications.

From a technical perspective, this solution is highly sophisticated: Given that the browser itself no longer supports Java, all the information provided by FirstSpirit (SSO, login process, project information, etc.) has to travel from the browser level to the operating system level of the local workstation via a different route. By definition, this route is highly secure because it is recognized as the potential gateway for outside attacks.  

Solution: A file system extension is registered by means of an OS specific implementation. Then, a .fslnch configuration file (signed XML file) is generated from the start page and downloaded from the browser (which is regarded as secure). This configuration file is then linked to the FirstSpirit Launcher and its first task is to ensure that the Java Environment and the JAR are downloaded from the FirstSpirit server (from the fs5root directory). The Launcher uses the configuration file to find out where these files are located. Then, the FirstSpirit applications can be started in the usual manner (SiteArchitect, ServerManager).

See FirstSpirit Launcher (→Documentation for Administrators).

Using the proxy settings of the operating system

The FirstSpirit Launcher supports the use of proxy operating system settings.

Supported proxy setting types in Windows and macOS:

• automatic proxy configuration via a PAC script
• manual proxy configuration

Configuration: Proxy settings are not taken into account in the default configuration. To use the proxy settings, the java.net.useSystemProxies=true parameter must be set in the connection settings (see Optional parameters (→Documentation for Administrators)).

Once the parameter (java.net.useSystemProxies=true) has been set, the proxies set in the operating system (including a configured PAC script where necessary) are evaluated and forwarded to the FirstSpirit Launcher.

If the proxy is deactivated, the default configuration is applied (direct connection without proxy).

Java 11 or later must be used for this to be supported.

Limitations when using the FirstSpirit Launcher

The following limitations have to be considered when using the FirstSpirit Launcher:

• In principle, the launcher runs on Linux, but this is not officially supported due to the large number of existing distributions. It is also be necessary to locally install a Java environment.

Firewall / Reverse Proxy 

If FirstSpirit is operated with SSO and firewall / reverse proxy, FirstSpirit must still be notified of the names of the session cookies used for authentication. The parameter clientCookieNames in configuration file fs-server.conf is used for this purpose (see Communication (→Documentation for Administrators))). Only then can Launcher-specific connections (e.g., for downloading resources and connecting SiteArchitect or ServerManager to the FirstSpirit Server) run in the context of the existing browser connection, without having to execute another authentication process at the reverse proxy / firewall.

There are just a few scenarios in which the required session cookies cannot be passed to the FirstSpirit Server and are instead intercepted by the reverse proxy / firewall. If SiteArchitect or ServerManager will not start in such cases, the ~/fs5root/jnlp/ directory must be released in the firewall. This release is not a security issue, as the Launcher only downloads resources from this directory, no other communication takes place over this path. What’s more, access is secured via random paths which are only available temporarily for the respective user session. The ~/fs5root/servlet area (which is protected by the FirstSpirit security filter) also needs to be released in the firewall for client-server communication over HTTP/HTTPs in such instances.

Installing FirstSpirit Launcher

Download FirstSpirit Launcher

To use the FirstSpirit Launcher on a local workstation, users need write and execution permissions in the following directories:

• C:\Users\{username}\AppData\Local\Programs\FSLauncher
• C:\Users\{username}\.firstspirit\FSLauncher

The Launcher and any log files from installation procedures and Launcher updates are located under ~\AppData\Local\Programs\FSLauncher.

Resources for starting FirstSpirit SiteArchitect and ServerManager (fs-isolated-client.jar, the JRE, and Launcher specific data) and the Launcher log files are located under ~\.firstspirit\FSLauncher.

If the user does not have the corresponding permissions, an exception will be thrown and it will not be possible to use the FirstSpirit Launcher.

If files in these directories are deleted manually, they will be rolled out again or created by the Launcher the next time the client is started.

The FirstSpirit Launcher must first be installed on the workstation of the user who is to use it. This can be done

1. for a local workstation only or
2. for multiple client workstations in a group

In both cases, the Launcher (under Windows in this example) is installed with the installation file FSLauncher.exe. This file can be downloaded via the FirstSpirit start page (“Download FirstSpirit Launcher” link).

1) Installation of the Launcher locally on the workstation

Install FirstSpirit Launcher (locally)

The file can be downloaded via the window that opens at the bottom left of the browser (via the “Install Launcher” link).

A new window opens: “Install FirstSpirit Launcher”.

Administrator rights are not necessary for local installation.

Installation of the FirstSpirit Launcher

To complete the installation of the launcher, the downloaded FSLauncher.exe must be executed.

A local user directory on the workstation is used for the installation (2):
C:\Users\<user name>\AppData\Local\Programs\FSLauncher

After clicking the “Finish” button, the launcher installation is complete.

2) Group-based installation of the Launcher on multiple workstations

In addition to the local installation, a group-based installation for several workstations can be executed. This can be done automatically via group policy (e.g. LDAP) via the silent mode of the installer:

FSLauncher.exe -q

Optionally, the installation folder can also be specified:

-dir %LOCALAPPDATA%\Programs\FSLauncher

(in this example the default value).

This way the launcher can be installed either on all client computers or only for a defined group of users.

In addition to the actual installation, the connection settings for the launcher can also be set centrally. If an external group is passed within the fs-server.conf configuration file via the externalLauncherGroup parameter, the connection settings for SiteArchitect and ServerManager for all users in this group are changed to the FirstSpirit Launcher (see Server (→Documentation for Administrators)).

If the launcher is automatically installed on several computers via group policy, automatic activation of the launcher on the FirstSpirit server also makes sense. External groups can be defined for which the launcher is set to be active. See Server (→Documentation for Administrators)

Automatic update of the FirstSpirit Launcher

The launcher is updated automatically after an update of the FirstSpirit server. If newer version of the launcher is available on the server, the FSLauncher.exe is downloaded and the installation is updated.

If the users do not have sufficient permissions (for the installation directory), the update process is abandoned and the absent permissions are logged. Updates have to be performed by the administrator.

Options for configuring the FirstSpirit Launcher

The FirstSpirit Launcher can be configured using the file

{FS Launcher installation path}/FSLauncher.vmoptions 

The following parameters can be used:

-DlauncherDir: This parameter can be used to define another directory where the launcher should place the downloaded and temporary files.
Example:

-DlauncherDir=c:/temp/FSLauncher/

Default value: ~Userhome/.firstspirit/FSLauncher
Note: Ths parameter replaces the parameter -Duser.home
To remove all temporary files from the user home directory, it is also necessary to set the CLIENT_HOME_DIR on the server side (see Roll-out process (workstation computer) (→Documentation for Administrators)).

-DuseLocalJre: This parameter can be used to define that the JRE used to start the Java clients should not be downloaded from the FirstSpirit server, but that a local JRE should be used instead.
Example:

-DuseLocalJre=true

Default value: false
Note: The JRE to be used is determined automatically. In most cases this will be the JRE used by the launcher itself.

-DlocalJre: This parameter can be used to define which local JRE is to be used. The path to the installation directory of the corresponding Java version must be specified as value.
Example:

-DlocalJre=c:/Program Files/Java/jdk-11/

Important: This parameter is only taken into account if -DuseLocalJre=true ist also set.