Installation (Connect Server)

Content

Requirements

The Connect Server requires .NET 5.0 (with ASP.NET Core) from patch level 5.0.4 as runtime environment. This can be downloaded via the following link:

On Windows, use the package Hosting Bundle, on other platforms, use the binaries for the appropriate processor architecture. Alternatively, you can also use the SDK, but this is not mandatory.

The required resources vary depending on the scenario. For orientation purposes, here are some recommendations for the use of internal ticket synchronization:

For small and medium-sized installations, you may use an existing (virtual) machine with sufficient capacity.

Make sure that the Connect runtime environment can communicate with all participating peripheral systems via http or https.

Installation on Windows

Installation as console application

Installing the Runtime Environment

Download the latest "Hosting Bundle" for the ASP.NET Core 5.0 runtime environment and run the installer. The download is provided by Microsoft at the following link:

Installing the Connect Server

Extract the ZIP archive containing the Connect Server to a folder.

Configuration of the Connect Server

The Connect Server is delivered with a ready-to-run configuration. The integrated web ­server is available on port 80 after startup and responds to HTTP requests. For more information on customizing the configuration, please refer to the Configuration chapter.

Starting the Connect Server

Open a shell (cmd), change to the folder with the Connect Server and start the executable file named "GalileoGroup.Connect.Server.Backend.exe".

Stopping the Connect Server

Activate the console window and stop the Connect Server by pressing Ctrl + C or close the Connect Server console window.

Installation as Windows service

Installing the Runtime Environment

Download the latest "Hosting Bundle" for the ASP.NET Core 5.0 runtime environment and run the installer. The download is provided by Microsoft at the following link:

Installing the Connect Server

Extract the provided ZIP archive with the Connect Server to a folder (e.g., "C:\Program Files\GalileoGroup\Connect").

Creating a local user to run the service

To create the local user, enter the following commands in a PowerShell with administrator privileges:

$accountName = "ConnectService"
New-LocalUser -Name $accountName

After The user has been successfully created, it must be assigned the permission to log in as a Windows service. Press the + R keys and enter secpol.msc in the following input window. Now a window will be displayed with a tree structure on the left side. There open the node "Local Policies" and then click on the node "Assign user rights". In the right half of the screen, select the "Log on as service" entry via double-click.

In the following dialog window, click the "Add user or group" button and select the newly created local user. If the user is not found, restrict the search path to the local computer name.

Now the new user must be allowed access to the folder where the application was installed. In this example, the folder "C:\Program Files\GalileoGroup\Connect" is used. To do this, enter the following commands in a PowerShell with administrator privileges:

$accountName = "ConnectService"
$fullPath = "C:\Program Files\GalileoGroup\Connect"
$User = Get-LocalUser -Name $accountName

if($User -ne $Null) {
  $acl = Get-Acl $fullPath -ea Stop
  $FileSystemRights = [System.Security.AccessControl.FileSystemRights]"Modify"
  $AccessControlType = [System.Security.AccessControl.AccessControlType]::Allow
  $InheritanceFlags = [System.Security.AccessControl.InheritanceFlags]"ContainerInherit, ObjectInherit"
  $PropagationFlags = [System.Security.AccessControl.PropagationFlags]"InheritOnly"
  
  $AccessRule = New-Object System.Security.AccessControl.FileSystemAccessRule ($User.SID, $FileSystemRights, $InheritanceFlags, $PropagationFlags, $AccessControlType)
  $acl.AddAccessRule($AccessRule)
  
  Set-Acl -Path $fullPath -AclObject $acl -ea Stop
  Write-Host ("Permission granted at {0}" -f $fullPath)
}

Registering the Connect Server as a Windows Service

Registration can also be accomplished using PowerShell. Here is an example which can be used as a template:

New-Service -Name ConnectServer -BinaryPathName "C:\Program Files\GalileoGroup\Connect\GalileoGroup.Connect.Server.Backend.exe". -Credential MYHOST\ConnectService -Description "Connect Server Service" -DisplayName "Connect Server" -StartupType Manual

Deregistering the Windows Service

If you want to remove the Windows service, you can do this with the following command in a shell with administrator privileges (please replace “<ServiceName>” with the name of the desired service):

sc delete <ServiceName>

Connect Server Configuration

The Connect Server is delivered with a ready-to-run configuration. The integrated ­web server is available on port 80 after startup and responds to HTTP requests. For more information on customizing the configuration, please refer to the Configuration ­chapter.

Installation as IIS Website

Installing the Runtime Environment

Download the latest "Hosting Bundle" for the ASP.NET Core 5.0 runtime environment and run the installer. The download is provided by Microsoft at the following link:

During installation, please note that the Connect Server provides its frontend as a WebAssembly and therefore requires some environment-specific configuration adjustments. Please discuss the exact procedure with our support team.

Installation on Linux

Preparations for CentOS

Since CentOS does not have the library for developing international Unicode components installed by default, you may have to install it manually. Proceed as follows:

sudo yum install libicu

Preparations for Debian

Since Debian does not have the library for developing international Unicode components and curl installed by default, you may have to install them manually. Proceed as follows:

sudo apt update
sudo apt install libicu-dev
sudo apt install curl

Creating the user

It is recommended to create a separate user for the execution of the Connect Server.

The following example shows the creation of a new user with the name "connect":

CONNECT_USER=connect

sudo useradd -m $CONNECT_USER
sudo passwd $CONNECT_USER

Installing the ASP.NET Core 5.0 Runtime

The installation can be done either via a package manager (global) or via the installation script provided by Microsoft.

Enter the following commands to download and execute the installation script:

CONNECT_USER=connect
su - $CONNECT_USER

DOTNET_ROOT=$HOME/.dotnet
DOTNET_INSTALL_URI=https://dot.net/v1/dotnet-install.sh
DOTNET_CHANNEL=5.0
DOTNET_RUNTIME=aspnetcore

curl -sSL $DOTNET_INSTALL_URI | bash /dev/stdin --channel $DOTNET_CHANNEL --runtime $DOTNET_RUNTIME --install-dir $DOTNET_ROOT

Alternatively, you can download the required package for Linux from https://dotnet.microsoft.com/download/dotnet/5.0 , place it in the home directory of the user created for Connect, and extract it as follows:

CONNECT_USER=connect
su - $CONNECT_USER

DOTNET_ROOT=$HOME/.dotnet
DOTNET_ARCHIVE=$HOME/aspnetcore-runtime-5.0.4-linux-x64.tar.gz

mkdir -p $DOTNET_ROOT
tar zxf $DOTNET_ARCHIVE -C $DOTNET_ROOT
rm $DOTNET_ARCHIVE

For general information about installing the .NET Core Runtime, see the following link:

Information about the installation script used can be found at the following link:

Installing the Connect Server

To install the Connect Server, copy the Connect Server archive and the custom configuration archive to the home directory of the user you created for Connect. Follow the steps below to install the software (replace the name config.tar.gz highlighted in blue) with the name of the archive of configuration data provided for your use:

CONNECT_USER=connect
su - $CONNECT_USER

CONNECT_ROOT=$HOME/connect
CONNECT_SERVER_ARCHIVE=$HOME/GalileoGroup.Connect.Server.Backend.tar.gz
CONNECT_CONFIG_ARCHIVE=$HOME/config.tar.gz

mkdir -p "$CONNECT_ROOT"

tar zxf "$CONNECT_SERVER_ARCHIVE" -C "$CONNECT_ROOT"
rm "$CONNECT_SERVER_ARCHIVE"

tar zxf "$CONNECT_CONFIG_ARCHIVE" -C "$CONNECT_ROOT"
rm "$CONNECT_CONFIG_ARCHIVE"

Connect Server Configuration

The Connect Server is delivered with a ready-to-run configuration. The integrated ­web server is available on port 80 after startup and responds to HTTP requests. For more information on customizing the configuration, please refer to the Configuration ­chapter.

Starting the Connect Server in foreground

To start the Connect Server in the foreground, proceed as follows:

CONNECT_USER=connect
su - $CONNECT_USER

DOTNET_ROOT=$HOME/.dotnet
CONNECT_ROOT=$HOME/connect

cd "$CONNECT_ROOT"

"$DOTNET_ROOT/dotnet" GalileoGroup.Connect.Server.Backend.dll

Starting the Connect Server in background

To start the Connect Server in the background, proceed as follows:

CONNECT_USER=connect
su - $CONNECT_USER

DOTNET_ROOT=$HOME/.dotnet
CONNECT_ROOT=$HOME/connect

LOG_DIR=$CONNECT_ROOT/log
LOG_FILE="$LOG_DIR/log-`date "+%Y%m%d-%H%M%S"`.txt"

mkdir -p $LOG_DIR

cd "$CONNECT_ROOT"

eval "nohup "$DOTNET_ROOT/dotnet" GalileoGroup.Connect.Server.Backend.dll >"$LOG_FILE" 2>&1 &"

echo "- PID: $!"
echo "- Output: $LOG_FILE"

We recommend creating a script for this action. You can find corresponding templates in the Scripts/Templates folder.

Stopping the Connect Server

To stop a Connect Server running in the foreground, press Ctrl + C.

To stop all Connect Servers running in the background, proceed as follows:

CONNECT_USER=connect
su - $CONNECT_USER

DOTNET_ROOT=$HOME/.dotnet

ps -af | awk "{ if (\$8 == \"$DOTNET_ROOT/dotnet\" && \$9 == \"GalileoGroup.Connect.Server.Backend.dll\") { printf \"%s\n\", \$2} }" | while read pid
do
  echo "Stopping process with PID $pid."
  kill $pid
done

We recommend creating a script for this action. You can find corresponding templates in the Scripts/Templates folder.

Installation using Docker

The Connect Server can run in Docker. On Windows, only the "modern" Docker variant (Docker with WSL2) is supported. We recommend using the portable .NET assembly package, since the platform-specific variants of the Connect Server are not explicitly tested for operation with Docker.

As a basis for the creation of the image you need a Linux distribution and the current version of the ASP.NET Core 5.0 runtime environment. Microsoft provides a corresponding image, but it may also be created according to your own requirements.

The Connect distribution package already contains a Dockerfile for creating an image of the Connect Server based on the ASP.NET 5.0 environment provided by Microsoft.

Before creating the image, the Dockerfile can be customized to your own requirements. The following example shows a Dockerfile for creating a container with the Debian based ASP.NET Core runtime, additional network tools, an editor, and the Connect Server:

FROM http://mcr.microsoft.com/dotnet/aspnet

LABEL Description="This image contains the Connect! Server." Vendor="Galileo Group AG" Version="2021.0510"

RUN apt -y update
RUN apt -y upgrade
RUN apt -y install net-tools
RUN apt -y install iputils-ping
RUN apt -y install vim

COPY . /connect/app

RUN rm -r /connect/app/Certificates

VOLUME /connect/data

WORKDIR /connect/app

ENV Connect__Server__Paths__RepositoryPath=/connect/data/repositories
ENV Connect__Server__Paths__CertificatePath=/connect/data/certificates

ENTRYPOINT ["dotnet", "GalileoGroup.Connect.Server.Backend.dll", "settings=/connect/data/appsettings.json?"]

EXPOSE 80/tcp
EXPOSE 443/tcp

To create the Docker image, start a shell and change to the working directory using the cd command. Execute the following command to create an image with the name "connect":

docker build -t connect .

In this example, the web server uses the default configuration inside the Docker image and can be reached via HTTP on port 80. Externally, any port can be used for the container.

To avoid keeping the persistent data inside the container, an external directory named "c:\connect\data" is created in this example. A JSON file with the name "appsettings.json" can be placed in this directory, to define environment-specific configuration settings.

If needed, required repositories can be placed in a subdirectory named "repositories".

In the following, a container with the name "myconnect" is created, which is based on the image "connect" and uses port 8000 for access via HTTP. To resolve server names, a DNS server must be specified for the container (in this example, 192.168.1.110). Create and start the container using the following command:

docker run -d -v c:\connect\data:/connect/data -p 8000:80 --dns 192.168.1.110 --name myconnect connect

If required, you may add a DNS suffix be specifying Parameter --dns-search <suffix> before parameter –name.

For more information, see the documentation at the following link: