XamFlow Server Installation Guide

This installation guide describes the process to install XamFlow Server on a computer running Microsoft Windows.

XamFlow Server is a central database which is accessed through web APIs.

Installation

Server Setup Tool

This guide describes the manual process to install XamFlow Server. Using the Server Setup Tool is recommended instead.

Database

• Open a new Command Prompt run as administrator

• Install PostgreSQL 15.x Win x86-64:

  set PG_INSTALL="C:\XamFlow\PostgreSQL\15"

  set PG_BIN="C:\XamFlow\PostgreSQL\15\bin"

  set PG_DATA="C:\XamFlow\Database\15"

  set PG_SERVICE_NAME=xamflow-postgresql-x64-15

  set PG_PORT=44308

  • https://www.enterprisedb.com/downloads/postgres-postgresql-downloads

  • postgresql-X.Y-Z-windows-x64.exe --mode unattended --unattendedmodeui minimal --prefix %PG_INSTALL% --extract-only 1

  • %PG_INSTALL%\installer\vcredist_x64.exe /install /passive /norestart

  • %PG_INSTALL%\installer\vcredist_x86.exe /install /passive /norestart

• Create a new cluster:

  • md %PG_DATA%

  • icacls.exe %PG_DATA% /grant *S-1-5-32-545:(OI)(CI)M

  • %PG_BIN%\pg_ctl.exe init -D %PG_DATA% -o "-A scram-sha-256 -E UTF8 --locale=""English, United States"" -U postgres -W"

  • Choose an arbitrary superuser password for the database.

• Register PostgreSQL as a Windows service:

  • %PG_BIN%\pg_ctl.exe register -D %PG_DATA% -N %PG_SERVICE_NAME% -U "NT Authority\NetworkService" -S auto -o "-p %PG_PORT%"

  • sc.exe config %PG_SERVICE_NAME% DisplayName= "XamFlow PostgreSQL Server"

  • sc.exe description %PG_SERVICE_NAME% "Provides relational database storage."

  • sc.exe start %PG_SERVICE_NAME%

• Create a new database xamflow:

  %PG_BIN%\createdb.exe -p %PG_PORT% -U postgres xamflow

• Run following SQL scripts in the given order:

  • init_migrations.sql

  • install_activitylog_0000-XXXX.sql

  • install_filestorage_0000-XXXX.sql

  • install_xamflowadmin_0000-XXXX.sql

  • install_xamflow_0000-XXXX.sql

  • init_superuser.sql

  You can run an SQL script with the following commands:

  %PG_BIN%\psql.exe -f install_xamflow_0000-XXXX.sql -U postgres xamflow

  (When asked provide the database superuser password specified when creating the PostgreSQL cluster above.)

• Run the following SQL commands, replace XXXX with the target version number of the file above:

  • SELECT public.complete_migration('activitylog', 'XXXX');

  • SELECT public.complete_migration('filestorage', 'XXXX');

  • SELECT public.complete_migration('xamflowadmin', 'XXXX');

  • SELECT public.complete_migration('xamflow', 'XXXX');

  You can run an SQL command with the following command:

  %PG_BIN%\psql.exe -c "SELECT public.complete_migration('xamflow', 'XXXX');" -U postgres xamflow

  (When asked provide the database superuser password specified when creating the PostgreSQL cluster above.)

IIS Web Server

Windows 10 or later

• Activate IIS by turning the following Windows Features on (in Control Panel):

  • Internet Information Services (Checking the top-level box checks some nested boxes.)

• Ensure the following boxes are checked:

  • Internet Information Services ‣ Web Management Tools ‣ IIS Management Console

• Some additional nested boxes must also be checked manually:

  • Internet Information Services ‣ World Wide Web Services ‣ Security ‣ Basic Authentication

Windows Server 2016 or later

• In Server Manager:

  • Add server role Web Server (IIS) with the following additional role services:

    • Web Server ‣ Security ‣ Basic Authentication

.NET

• Install Microsoft .NET 8.0 Server Runtime

  • https://aka.ms/dotnet/8.0/dotnet-hosting-win.exe

Web Services

• Extract the contents of Lucid.XamFlow.WebApi win64.zip into the folder C:\inetpub\apps\xamflow\.

  • Create a Logs subdirectory and grant Modify permission to Users.

  • Create a Config subdirectory and grant Modify permission to Users.

• Create and import certificates (see Certificates Guide).

• Start IIS Manager.

• Server Certificate:

  • Import a X.509 certificate for the domain name of the machine.

• Add the following application pool:

  • XamFlowServerAppPool

• Add the following website:

  • xamflow

    • application pool: select XamFlowServerAppPool

    • physical path: C:\inetpub\apps\xamflow\

    • port: 44303

    • binding: https (Use the certificate imported before.)

    • host name [1]: domain name of the machine (same as DNS Name in Subject Alternative Name of certificate)

• Restart IIS

Footnotes

[1]

The host name field in the IIS website dialog might be disabled. To enable it, make sure the friendly name of your certificate starts with an asterisk * character. See the Certificates Guide for how to edit the friendly name of your certificate.

Configuration

• Open XamFlow WebAdmin (https://your-domain-name:44303/admin/):

  • Login as XamFlow superuser with password superuser.

  • Adjust the XamFlow superuser password.

  • Create a user.

  • Create a user group.

  • Add the user to the user group.

  • Give the group admin permission if desired.

  • Optional: Create further users, groups and permissions.

  • Register a file storage mapping for @xf/.

    • Create the mapped folders on disk and grant Modify permission to Users.

Windows Firewall

• Create an inbound rule for TCP ports 44303 to allow access.

Troubleshooting

In case of problems, please see the log files in following locations:

• Application log: C:\inetpub\apps\xamflow\Logs\

• IIS Access log: C:\inetpub\logs\LogFiles\W3SVC...\

• IIS HTTP Error log: %SystemRoot%\system32\LogFiles\HTTPERR\httperr1.log

• IIS Trace Logging for failed requests: C:\inetpub\logs\FailedReqLogFiles\

(Note: You may have to tell Windows that you want to access a protected parent folder first.)