Introduction / Server: Installation and Migration

Server Installation (Switch to Isolated Mode)

Table of contents

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.

Important 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.

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


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

Installing from a tar.gz archive consists of 5 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/jdk1.8.0_181).
    (Alternatively the complete Java path can also be specified in the file fs-wrapper.isolated.conf, with the parameter
  • Start the FirstSpirit servers for the first time:
    • under Linux with ~FS/bin/fs5 start
    • under Windows with ~FS\bin\fs5 install and ~FS\bin\fs5 start (by starting the service just installed)
      or alternatively with ~FS\bin\fs5.cmd console (without using a Windows service)

Attention! For fs5 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\fs5 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.
  • Services also have to be managed by the administrator - with firstspirit5/bin/fs5.init we are providing an example for SysV-Init.

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:


(also referred to as update archive)
This probably affects installations made with FirstSpirit 2018-10 (October 2018) and earlier.

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

~/firstspirit5$ tar xvfz fs-update-1.0.1.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.

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) Set “isolated” flag

Once the server has shut down, a flag is set to “isolated ”via the “FS_MODE” environment variable or alternateley, the value (“isolated”) is manually written into the bin/fs5.mode file.

4) Start the server

The server can then be re-started (as an isolated server) in the usual way via the fs5 command. Upon successful conversion the web applications will automatically be rolled out again when the server re-starts.

For more information on installing or updating a FirstSpirit Server, see “FirstSpirit Installation Instructions” ().

© 2005 - 2024 Crownpeak Technology GmbH | All rights reserved. | FirstSpirit 2024.4 | Data privacy