OneOffixx server installation

Note

This page concerns the OnPremises option.
With the "Software as a Service" option, no server installations by the customer are necessary.

Before you start:

Prerequisite for the installation of the OneOffixx server is a Microsoft SQL Server database to store the data. If you cannot use an existing database server, you can perform a SQL Express installation as described here. The correct configuration of the SQL user for OneOffixx is described here.

Installation

The installation package contains a PowerShell script "Install.ps1" that performs the installation. The script must be run as administrator because, among other things, missing Windows features are activated.

Note

The installation script ("Install.ps1") is designed to install exactly one OneOffixx environment on one server. If multiple OneOffixx environments are to run on the same server, then additional manual configuration steps are required. See Multiple In-Process Applications in same Process in the Troubleshooting.

Execution Policy

To run the script, the execution policy must be set to Unrestricted:

Set-ExecutionPolicy Unrestricted

If you want to adjust the execution policy only temporarily for the installation, it can be set as follows:

Set-ExecutionPolicy Unrestricted -Scope Process

The following question must be answered with y for "Yes":

Execution Policy Change
The execution policy helps protect you from scripts that you do not trust. Changing the execution policy might expose
you to the security risks described in the about_Execution_Policies help topic at
http://go.microsoft.com/fwlink/?LinkID=135170. Do you want to change the execution policy?
[Y] Yes  [A] Yes to All  [N] No  [L] No to All  [S] Suspend  [?] Help (default is "N"): y

Run script

The installation zip file must be unpacked beforehand.

In the "Install_Customization.ps1" file, adjustments can be made if it is not a standard installation. The corresponding setting options are described in the file.

When calling "Install.ps1", arguments can be given. These are described in the file in a large comment (in "Usages").

Standard call (for this you must first navigate to the installation directory, e.g. with cd "C:\temp\OneOffixx_Install_Package"):

.\Install.ps1 `
    -HostUrl "https://oneoffixx.local" `
    -DbConnectionString "Data Source=...;Initial Catalog=OneOffixx_Prod;User id=...;Password=...;MultipleActiveResultSets=True" `
    -OperationDbConnectionString "Data Source=...;Initial Catalog=OneOffixx_Prod_Operation;User id=...;Password=...;MultipleActiveResultSets=True"

Further call options are described in "Install.ps1" in "Usages", e.g. the specification of a service account, if no SQL user is to be used.

The two databases from the above example ("OneOffixx_Prod" and "OneOffixx_Prod_Operation") can either already exist as empty databases. Otherwise they will be created automatically by the OneOffixx server applications (for conditions see SQL server roles / permissions).

Note

When installing the "WithoutIdS" option (see Options), no OperationDbConnectionString is needed.

By default, the script asks the user for information and confirmations. If this is not desired, -Force $true can be supplied as an argument.

Script procedure

1. Check required Windows features

In the first step it is checked whether all the required Windows features (including the Internet Information Service (IIS) with ASP.NET and WCF services and others) as well as the hosting bundle for .NET Core applications are installed.

2. "OneOffixx" website in IIS

In the next step it is checked whether a "OneOffixx" website is already registered with its application pools in IIS. If this is the case, it will continue with the next step.

If the website is not found, you will be asked if it should be created, with the installation path and port specified. The default settings are shown in the output. The script also creates the following application pools in IIS:

  • OneOffixx-Managed:
    Responsible for the .NET Framework-based server applications, such as the "Service" or the "Admin".
  • OneOffixx-Unmanaged-[...]:
    For all .NET Core-based server applications, a separate application pool is created, such as OneOffixx-Unmanaged-AddressService for the "AddressService" or OneOffixx-Unmanaged-HealthMonitor for the "HealthMonitor".

3. "OneOffixx" web applications

In this step the actual web applications are put in the "OneOffixx" website. If the applications are already installed, you will be asked if an update should take place. Then, this is a server update, in which case we recommend contacting our support.

4. "OneOffixx JobHost" scheduled task

In the last step you are asked, whether the "OneOffixx-JobHost" should be set up as a "scheduled task". The OneOffixx JobHost is a console program that updates user data in the background at a certain interval, for example. Therefore, it should be installed.

Completing the server installation

After the installation, both the IIS and the web applications and the scheduled task should be installed.

Tip

In the default installation, a website is created that listens on port 80. If there are several websites running on the same server, this could lead to conflicts. In that case the OneOffixx website will not start.

Service Account

The default installation assumes the use of an SQL user. However, it is also possible to run the OneOffixx server applications using a service account. For this, ensure the following configuration:

  1. The service account can connect to the SQL Server or to the future database.
  2. The service account is a member of the "IIS_IUSRS" group.
    This step is done automatically by the installation script if a security account is specified when calling it via arguments (see "Usages" in "Install.ps1" file) and the corresponding query is confirmed..
  3. For the IIS_IUSRS group, Log on as batch and Impersonate a client after authentication must be stored in the Local Security Policy (this corresponds to a standard IIS installation).
    Administrative Tools → Local Security Policy → Local Policies → User Rights Assignment
  4. The service account has modification rights on the OneOffixx application and log directory (in the default installation this is the same folder).
    This step is automatically taken care of for the application directory by the installation script if a security account is specified when called via the arguments (see "Usages" in "Install.ps1" file) and the corresponding prompt for change rights is confirmed.
  5. The service account must be stored in IIS as a user in all OneOffixx application pools.
    IIS → Application Pools → Advanced Settings → Identity → Custom account
    This step is done automatically by the installation script if a security account is specified when called via the arguments (see "Usages" in "Install.ps1" file).
  6. The service account must be stored as executing user in the "OneOffixx.JobHost" task.
    Task Scheduler → Task Scheduler Library → OneOffixx.JobHost → Properties
    This step is done automatically by the installation script if a security account is specified in the call via the arguments (see "Usages" in "Install.ps1" file).
  7. The service account is used in SQL-ConnectionString (passed as argument during installation or customize it in "OneOffixx.config"-file).
    This step is done automatically by the installation script if the correct ConnectionString is specified in the call via the arguments (see "Usages" in "Install.ps1" file).