Server Installation (Switch to Isolated Mode)

Starting with FirstSpirit 2019-02 the Isolated Mode is the default mode for newly installed servers. See below for instructions on how to migrate an existing server (Legacy Mode).

It is generally possible to migrate a server to Isolated Mode even if not all modules have been adapted yet. See chapter Ensuring the Compatibility of Existing Modules.

Note: The designation of the server version (e.g. on the start page, under Server version / Show all details) indicates whether or not a server is operated in Isolated Mode. In Isolated Mode the version number is extended with the tag “(I)”.

Differences between Isolated and Legacy Server

• Unlike Legacy Server, Isolated Server uses the file fs-isolated-server.jar (instead of fs-server.jar).
• The files fs-isolated-server.jar and wrapper.jar are located in the server/lib-isolated directory (instead of server/lib).
• Instead of the configuration file for the wrapper fs-wrapper.conf the file fs-wrapper.isolated.conf is used in Isolated Mode.
• On FirstSpirit servers that are operated in Isolated Mode, the value “isolated” will be found in the bin/fs5.mode file. Otherwise the server will start in Legacy Mode.
• The content of the file fs5.mode is ignored and the server is always started in Isolated Mode.

New installations in Isolated Mode

By default, FirstSpirit servers newly installed with FirstSpirit 2019-02 or higher are installed in Isolated Mode. The installation is carried out via the file

fs-install-[version].tar.gz

It is available by download (for access data please contact Technical Support).

Installing from a tar.gz archive consists of five steps:

• Unpack the install archive. Where necessary the archive has to be decompressed first (G(un)zip), then extracted.
• Copy the FirstSpirit server file (fs-isolated-server.jar) for the desired FirstSpirit version to the directory ~FS/server/lib-isolated. (~FS = directory containing the FirstSpirit server installer files)
• Copy the license file (fs-license.conf) to the directory ~FS/conf. (The license file can be requested from your designated Account Manager or via Technical Support.)
• Set the environment variable FS_JAVA_HOME to the directory with the desired Java version (e.g. FS_JAVA_HOME=/opt/java/jdk17.0.3+7).
  (Alternatively the complete Java path can also be specified in the file fs-wrapper.isolated.conf with the parameter wrapper.java.command.)
• Start the FirstSpirit servers for the first time:
  • under Linux with ~FS/bin/fs-server start
  • under Windows with ~FS\bin\fs-server install and ~FS\bin\fs-server start (by starting the service just installed)
    or alternatively with ~FS\bin\fs-server console (without using a Windows service)

Attention! For fs-server install under Windows you need system administrator privileges.

The installation is done in Isolated Mode, 8000 is used for the HTTP port and 1088 for the socket port.

Installing the Windows service

• ~FS\bin\fs-server install
  The Windows service can be configured via the wrapper.ntservice.* parameters in the file fs-wrapper.isolated.conf.

Installing with a different port

• Before step 5) you can modify HTTP_PORT and/or SOCKET_PORT in the file ~FS/conf/fs-server.conf.

Hints for installing FirstSpirit under Linux:

• We strongly advise against operating FirstSpirit as the root user.
• Users and groups are not created automatically, i.e. the administrator has create and configure an account before installing FirstSpirit.
• For the installation of the service "fs-server", ~FS/bin/fs-server install can be used.

Migration to Isolated Mode

1) Update the operations layer with fs-update[-version].tar.gz

If the operations layer (Java Wrapper and configuration files) are not completely up-to-date, or have been installed with a file fs-installer-[version].tgz (instead of with the new file fs-install-[version].tar.gz, available since FirstSpirit 2018-11), the operations layer first should be updated, using the following file:

fs-update-[version].tar.gz

(also referred to as update archive)

To update the operations layer unpack the archive in your FirstSpirit server directory.
Example call under Linux:

~/firstspirit5$ tar xvfz fs-update-3.0.6.tar.gz

After unpacking take note of the unpacked files' user and group access right, and adjust them if necessary. The permissions should be assigned in the same way as they apply to the FirstSpirit installation.

The previously unused file ~FS/conf/fs-wrapper.isolated.conf should be overwritten with the file ~FS/conf/conf-all/fs-wrapper.isolated.conf.default.txt so that the currently recommended startup parameters can be used. Special settings (e.g., name of the Windows service, manually configured Java version) should then be supplemented or taken from ~FS/conf/fs-wrapper.conf.

2) Store fs-isolated-server.jar in the server directory

First option for changing over to an isolated server: store the fs-isolated-server.jar in the server directory under the server/lib-isolated path. The fs-server.jar (or even the server/lib directory) can be deleted after the migration is completed. The name of the fs-isolated-server.jar file is irrelevant (as long as it ends in .jar), and only one version of the file may exist in the directory!

Then shut down the FirstSpirit Server (Legacy Mode).

3) Copy classes and jars
If there are files in the directories ~FS/shared/lib or ~FS/shared/classes, they must be copied to the directories ~FS/shared/lib-isolated and ~FS/shared/classes-isolated.

Corresponding libraries should instead be better provided as a module.

4) Starting the Server
Finally, the server can be restarted as usual using the command fs-server (as an Isolated Server). After a successful transition, the web applications will be automatically redeployed upon the first server restart.

5) Cleanup
If the FirstSpirit server can be used without issues in Isolated Mode, the following directories can be deleted:
~FS/shared/lib
~FS/shared/classes
~FS/server/lib
~FS/server/classes
Additionally, in the ~FS/bin directory, all files that begin with fs5 can be deleted.

Note for Windows operating system

If FirstSpirit is used as a service on a Windows operating system, the old service must be uninstalled.

fs5 remove

After updating the operating environment (and any necessary adjustments to the fs-wrapper.isolated.conf as well as the fs5.mode file), the service is reinstalled using

fs-server install

Both actions require Windows administrator permission.

For more information on installing or updating a FirstSpirit Server, see Installation (→Documentation for Administrators)