Workflow Server Deployment

IIS deploy

Prerequisites

1. A database must be setup and operating, according the instructions available here.

2. Setup parameters (at least, these: Provider, ConnectionString, ServerType, LicensePath) must be set in the config.json file. It is described in the Configuration section.

3. Besides, the archive with Workflow Server source code is required. It can be downloaded from our site.

4. Hosting Bundle for .NET 8.0 should be installed also to run an ASP.NET Core application in IIS. It includes ASP.NET Core runtime. Hosting Bundle can be downloaded from the official website in the following link.

5. Since Workflow Server uses .NET 8.0, please, install the appropriate version using the link.

6. Be sure that .NET Core Runtime is properly installed by running on a command prompt or Powershell:

   dotnet --list-runtimes

7. In addition, it is highly recommended disabling antivirus software and firewall temporarily to avoid socket connection errors.

note

Update or installing the .NET most recent version is a good practice.

Deploy

1. First at all, the directory: wfs where will be deployed the project must be created and inside two folders: 'admin' and 'forms' which will contain the assemblies for the admin panel and for the form manager. The following hierarchy should be considered:

   ├── wfs
       ├──admin
       └──forms

2. Then, the folders: ‘backend’ and ‘frontend’ must be copied from the downloaded WFS archive into the created directory to be used for IIS deployment. Since Workflow Server implements two web hosts, one for the admin panel and web API, and another for the form manager, two applications have to be created.

info

Check that the wfs project is built and run properly by using the IDE framework.

3. Open WorkflowServer.sln in JetBrains Rider or Visual Studio. Press the right-click mouse button in WorkflowServer project, and select: 'Publish...' -> 'Create new' -> 'Local folder' in the pop-up window.

4. Create a new configuration in JetBrains Rider for publishing the WFS project in IIS. Set the ‘Target location’ as: wfs/admin/, leave the rest default settings and publish it. After that, repeat this step in order to publish the project once, but in the other directory: wfs/forms/.

5. Move to the folders: ‘admin’ and ‘forms’, there will be available all the files once the project is published.

info

Make sure that the web.config file is present in each of the domain folders.

6. Open the file: config.json in each directory: wfs/admin/ and: wfs/forms/. The following changes must be done:

• For admin:

  {
    "BackendFolder": "../backend",
    "IsMultiServer":  true,
    "ServerType": "Admin",
    "PathBase": "/admin/",
    "RedirectHosts": [ "http://localhost:8077", "http://localhost:8078", "http://localhost:your_chosen_port", "http://localhost:your_chosen_port/forms/" ],
  }
• For the forms:

  {
    "IsMultiServer":  true,
    "ServerType": "Forms",
    "PathBase": "/forms/",
    "AuthorityUrl" : "http://localhost:your_chosen_port/admin/",
  }

7. Moreover, it must be set properly the path to the license.key file in: config.json as is indicated below:

   "LicensePath": "../license",

8. Open the IIS Manager. On the left panel is located the 'Sites' folder, press the right-click mouse button and select the option: 'Add Website…'. In the emerged window, specify the path or content directory that was created for deploying the WFS project , the site name can be set: ‘wfs’, and also the application pool which is created automatically with this site. Then, write the chosen port - any free and press: 'ok'.

9. Select: 'Edit Application Pool' -> 'Recycling...', in the dialog box that appears, turn off the Regular time intervals (in minutes) option. Then, click on 'Next' -> 'Finish'.

10. Next, move to: 'Edit Application Pool' -> 'Advanced Settings'. In the window that appears, find the 'Process Model' -> 'Idle time-out ( minutes)' option, and change its value from 20 to 0. In addition, 'Load User Profile' must be set to 'True' in order to avoid startup failures or hosting issues. Press 'ok', the wfs admin pool is set up.

info

The Application pool wfs for the admin site, it should be set up to avoid unnecessary restarts of the Workflow Server runtime or shutdowns when idle.

11. An additional application pool must be created for the form manager, so it can be defined as: ‘wfs_forms’.

12. Afterward, click on the wfs site by using the right-click mouse button and select: ‘Edit permissions’ in order to assign full rights to IIS and both application pools. Moreover, the full permissions for the IIS user accounts: IIS_IUSRS or IUSR must be set in the root directory where the project is being deployed.

13. Furthermore, it is required to add the applications to the wfs site in IIS, one application - one server. Right-click on wfs site and select: ‘Add application...'

• For admin, the alias has to be set as is defined in: config.json in PathBase, that is, 'admin'. The path - the corresponding directory, in this case: 'wfs/admin', select also the application pool: 'wfs'.

• In case of forms manager, an application should be added as well. Set also the appropriate alias: 'forms', the path: 'wfs/forms', and the application pool: ‘wfs_forms’.

info

Be sure that full control permission are set for these directories for ApplicationPoolIdentity (or user which is being used in Application Pools).

14. Alternatively, publishing can be performed without an IDE framework, through the command line. In the WorkflowServer project directory, containing WorkflowServer.sln, run the command:

    dotnet publish WorkflowServer.sln -o <WFS_ADMIN_PATH>
    • Where <WFS_ADMIN_PATH> - It is the path to the admin folder that was created.

    If the admin folder is not available on the computer where the application is being developed, any available folder can be selected for publishing. In this case, its contents should be copied to the admin folder.

15. Once IIS deploy is done; both the admin panel and the form manager are accessible according to the IIS binding sets which were specified for the wfs admin and the wfs forms application respectively.

16. In case of any issues, please check the steps you've taken in the Troubleshooting section.

IIS deploy troubleshooting and Checkup list

Ensure the following steps have been completed:

• Set full control permission for the 'admin' and 'forms' folders for ApplicationPoolIdentity (or user which you use in Application Pools).
• Provide correct paths to frontend and backend paths which are indicated in the config.json file.
• Allocate free, vacant and non-conflicting port to the domains: admin and forms.
• The web.config file is successfully copied to both the 'admin' and 'forms' folders.
• Check that .NET Core Hosting Bundle proper version is installed.

Docker deploy with nginx as a reverse-proxy

Workflow Server might be deployed by implementing nginx as a reverse-proxy, in that case at least two Docker containers are required; one for Workflow Server, and another for nginx. Docker Compose can be used to manage these containers, and also it can be taken the docker-files/docker-compose-mongo.yml from the workflowserver project as base solution for deploying Workflow Server and MongoDB. This solution consists of the following three containers:

• db – MongoDB container.
• workflowserver – Workflow Server container.
• start_db – the container to prevent the workflowserver container from starting until MongoDB is fully activated and ready to accept queries.

When working through a reverse-proxy to correctly determine the IP address and client protocol in WFS, the forwarded headers must be enabled. The ProxySettings property in ServerSettings to configure forwarding is used as follows:

public class ProxySettings
{
  public List<string> KnownNetworks { get; set; } = new List<string>();
  public List<string> KnownProxies { get; set; } = new List<string>();
  public List<ForwardedHeaders> Headers { get; set; } = new List<ForwardedHeaders> { ForwardedHeaders.XForwardedFor, ForwardedHeaders.XForwardedProto };
  public bool Enabled { get; } = true;
}

Where Headers is the list of headers to be forwarded. Possible values are:

• XForwardedFor
• XForwardedHost
• XForwardedProto

More info can be read here.

For security reasons, header forwarding should be restricted to trusted proxies only. You can set the trusted proxies using the following properties:

• KnownNetworks - the list of trusted subnets in the CIDR notation (IP address / mask).
• KnownProxies - the list of the IPs of trusted proxy servers.

ProxySettings parameters can be configured using both config.json and environment variables. Considering debugging purposes, the ProxySettings can be used without specifying KnownNetworks or KnownProxies, then the headers are forwarded for any addresses. Set the environment variable ProxySettings__Enabled to true to enable this mode.

caution

In production mode, ProxySettings without specifying KnownNetworks or KnownProxies are not recommended.

1. First at all, the parameters of the subnet for the containers have to be defined. The subnet is created when the compose project is launched for the first time; thus, the project can be run by using: startcontainer.bat or startcontainer.sh, and then stop it by pressing: Ctrl+C. In the command prompt, execute the following:

   docker network inspect docker-files_default

   It shows the default networking information related to WorkflowServer project.

   In this case, the default network has 172.20.0.0/16 mask and 172.20.0.1 gateway. The containers are given dynamic addresses on creating. Should be assigned static addresses to set KnownProxies for the existing containers by adding a node to each service configuration:

   network:
     default:
       ipv4_address: <IP_address>  
   • Where <IP_address> - It is a unique IP-address within 172.20.0.2 - 172.20.1.254.

   

2. The configuration file: default.conf must be created in the directory: docker-compose/nginx/conf.d. It contains the following information:

    server {
        listen 8077;
        location / {
            proxy_pass         http://workflowserver:8077;
            proxy_http_version 1.1;
            proxy_set_header   Upgrade $http_upgrade;
            proxy_set_header   Connection $http_connection;
            proxy_set_header   Host $host;
            proxy_cache_bypass $http_upgrade;
            proxy_set_header   X-Forwarded-For $proxy_add_x_forwarded_for;
            proxy_set_header   X-Forwarded-Proto $scheme;
        }
   }
   
   server {
        listen 8078;
        location / {
            proxy_pass         http://workflowserver:8078;
            proxy_http_version 1.1;
            proxy_set_header   Upgrade $http_upgrade;
            proxy_set_header   Connection $http_connection;
            proxy_set_header   Host $host;
            proxy_cache_bypass $http_upgrade;
            proxy_set_header   X-Forwarded-For $proxy_add_x_forwarded_for;
            proxy_set_header   X-Forwarded-Proto $scheme;
        }
   }

   This file describes the two servers which correspond to the Workflow Server web hosts: Admin Panel/Web API and Form Manager.

   • Line 2:

     listen 8077;

   It sets the external port to access Admin Panel/Web API.

   • Line 4:

     proxy_pass         http://workflowserver:8077;

   It indicates the Admin Panel/Web API address in the internal network. The workflowserver host name corresponds to the service name in the docker-compose-mongo.yml configuration file, and the port number must match the url that is specified in config.json. Similarly, line 16 defines the external port to access Form Manager, and line 18 indicates the Form Manager address in the internal network (the port number must match DefaultFrontendPort specified in config.json).

   

3. In docker-compose-mongo.yml must be removed the ports from the workflowserver container, making it inaccessible from the external network:

   ports:
     - "8077:8077"
     - "8078:8078"

4. Afterward, the following description of the nginx container in docker-compose-mongo.yml should be added:

   nginx:
   depends_on:
     - workflowserver
   image: nginx:latest
   volumes:
     - ./nginx/conf.d:/etc/nginx/conf.d:ro
   ports:
     - "8077:8077"
     - "8078:8078"
   networks:
     default:
         ipv4_address: 172.20.0.5

   

5. The following line must be included in docker-compose-mongo.yml in the environment node of the workflowserver in order to add the nginx server IP-address to the list of KnownProxies,

   ProxySettings__KnownProxies__0: 172.20.0.5

   

6. The docker-compose-mongo.yml is ready, the complete file can be read below:

   version: '3.4'
   
   services:
     db:
       container_name: workflowserver-mongo
       image: mongo
       environment:
         MONGO_INITDB_ROOT_USERNAME: root
         MONGO_INITDB_ROOT_PASSWORD: mongopassword
       volumes:
         - dbdata:/data/db
       restart: always
       ports:
         - "27017:27017"
       networks:
         default:
           ipv4_address: 172.20.0.2
     start_db:
       container_name: workflowserver-mongo-wait
       image: mongo
       depends_on:
         - db
       volumes:
         - ./:/home/.docker
       entrypoint: /home/.docker/wait-for-mongo.sh workflowserver-mongo root mongopassword
       networks:
         default:
           ipv4_address: 172.20.0.3
     workflowserver:
       container_name: workflowserver
       hostname: workflowserver
       depends_on:
         - db
       build:
         context: ..
         dockerfile: ./WorkflowServer/Dockerfile  
       volumes:
         - ./../logs:/app/wfs/logs
         - ./../license:/app/wfs/license
         - ./../metadata:/app/wfs/metadata
         - ./../InitialScripts:/app/wfs/InitialScripts
       environment:
         ConnectionString: mongodb://root:mongopassword@workflowserver-mongo:27017/ws?authSource=admin
         Provider: mongodb
         LicensePath: /app/license/  
         MetadataFolder: /app/metadata/
         DefaultLoggerConfig__FileTarget__0: Information
         DefaultLoggerConfig__FileTarget__1: Error
         DefaultLoggerConfig__FileSettings__FileName: /app/logs/log.txt
         DefaultLoggerConfig__FileSettings__RollingInterval: Day
         DefaultLoggerConfig__FileSettings__RetainedFileCountLimit: 30
         ProxySettings__KnownProxies__0: 172.20.0.5
       networks:
         default:
           ipv4_address: 172.20.0.4
     nginx:
       depends_on:
         - workflowserver
       image: nginx:latest
       volumes:
         - ./nginx/conf.d:/etc/nginx/conf.d:ro
       ports:
         - "8077:8077"
         - "8078:8078"
       networks:
         default:
           ipv4_address: 172.20.0.5      
   volumes:
       dbdata:
         name: wfs-mongo-data

7. Finally, the containers can be run by using the following command:

   docker compose -f docker-compose-mongo.yml up

   

As is shown in the logs, requests come from 172.20.0.1 (the client IP-address) to: docker-files-nginx-1 (the reverse-proxy server) and successfully are redirected to: workflowserver-mongo, where WorkflowServer is running. Then, Workflow Server correctly defines the RemoteIPAddress of the client as: 172.20.0.1.