Containerization of WEBCON - version 2026

Applies to version: 2026.1.x and above; authors: Jakub Kawa, Tomasz Błach

This is an updated version of the original article: Containerization of WEBCON BPS

Introduction

With the release of version 2023.1.x of the system, the ability to containerize WEBCON components was introduced. Starting with version 2026.1.x, the container startup model has been simplified — instead of separate images for the Portal and the Service, a single bootstrapper image is provided, which, depending on the STARTUP_MODE environment variable passed to it, starts as either WEBCON Portal or WEBCON Workflow Service. Search Server (Solr) remains a separate image, because it is built on Linux.

Containerization is an alternative to the standard installation of WEBCON components and is particularly useful when using cloud services, significantly simplifying the installation of the system in such an environment.

This article provides a step-by-step guide to preparing an installation of WEBCON in which the core components run in independent containers (Portal and Service in separate containers).

Note: running WEBCON components in containers is possible only for users holding subscription licenses. Starting an additional container will consume another license. If a container is shut down correctly, the license is released. A report on license usage is available in WEBCON Designer Studio.

In addition, an external authentication provider will be required, e.g. Microsoft Entra ID or OpenID Connect, since Windows authentication does not work correctly inside containers.

Choosing a containerization platform

Thanks to the use of Docker images, WEBCON can be installed and run in containers on many platforms (most containerization platforms use Docker images).

In this article, containers will be created and run using Docker Desktop. This program must be installed beforehand, and all installation steps must be performed on the same computer.

Following the same approach as in the example described here, WEBCON can be installed in containers on any containerization platform (e.g. Azure Container Instances or Azure Kubernetes Service).

One image — startup modes

The Portal and the Workflow Service are started from the same webconbps/bootstrapper image. The role of the container is determined solely by the STARTUP_MODE environment variable:

When the container starts, the entrypoint script reads STARTUP_MODE, sets the enabled flags in the module configuration files, and starts the WebCon.WorkFlow.Bootstrapper.exe process. There is no need to manually edit the configuration files inside the image.

Image location

The images are published in the Docker Hub registry:

• bootstrapper (Portal and Workflow Service): https://hub.docker.com/r/webconbps/bootstrapper

• Search Server (Solr): https://hub.docker.com/r/webconbps/search

A list of available versions can be found under the Tags tab in both repositories.

Image tag

The tag of the bootstrapper image consists of the WEBCON version number and the name of the base operating system image:

webconbps/bootstrapper:<version>-windowsservercore-ltsc2022

In this article, version 2026.2.2.121 is used, i.e. the image:

webconbps/bootstrapper:2026.2.2.121-windowsservercore-ltsc2022

The bootstrapper image is built on top of mcr.microsoft.com/dotnet/aspnet:10.0-windowsservercore-ltsc2022, and therefore requires Docker Desktop to be running in Windows container mode with process isolation (--isolation=process). The Search Server image is a Linux image, so it must be created while Linux container mode is switched on.

Installation plan

During the installation of WEBCON in containers, only the database is created using the installer. The remaining system components must be downloaded as Docker images and started in containers using the appropriate commands.

For this reason, it is good practice to plan the environment in advance, listing the system components, their network addresses, and the communication between them.

The diagram below shows the installation described in this article together with the addresses of the individual services.

In this article we use Docker Desktop. All the core WEBCON components can be installed in it. Only the system databases must be created on an existing Microsoft SQL Server instance accessible from the computer on which WEBCON is running in containers.

Installation steps:

1. Create the WEBCON Search Server container and initialize the Solr search indexes.
2. Create the SQL databases using the WEBCON installer.
3. Create the Docker network and the environment variable files.
4. Create the WEBCON Workflow Service container.
5. Create the WEBCON Portal container.
6. Create the reverse proxy container.
7. Start Designer Studio and activate the license.

Data storage

The platform uses two types of databases. All data entered by users, as well as configuration data, is stored in relational Microsoft SQL Server databases. In addition, a large part of this data feeds the Solr search indexes handled by Search Server.

Creating the Search Server container

1. The Search Server container image is built on the official Solr platform image for Linux. Because of this, Docker Desktop must be switched to Linux container mode – right-click the program icon in the system tray and select the following option from the drop-down list:

2. After a moment you will see a warning like the one below. Click Switch to enable support for Linux containers.

3. A container is, by design, an ephemeral object. Because of this, you must make sure that data is not lost when the container is shut down. In Docker Desktop, this is handled by the Docker Volume mechanism, which lets you create dedicated volumes responsible for storing the data generated and used by the program in question.
   
   Create a new volume for Solr named solr-bps – open a CMD console and enter the command:
   
   docker volume create solr-bps

4. The created volume can be viewed in Docker Desktop under the Volumes tab:

5. To start the container, enter the following command in the CMD console:
   
   docker run -d --name bps_search -p 8983:8983 -e SOLR_HEAP=2g --mount source=solr-bps,target=/var/solr --add-host host.docker.internal:host-gateway --entrypoint /bin/sh webconbps/search:2026.2.2.121 -c "/opt/bps-solr/scripts/run-precreate-cores.sh"
   
   where:

• -d – runs the container in the background,
• --name bps_search – the container name,
• -p 8983:8983 – maps host port 8983 to container port 8983 (the default port on which Solr runs),
• -e SOLR_HEAP=2g – limits the memory allocated to the Solr process. Additional Solr environment variables can be passed in the same way,
• --mount source=solr-bps,target=/var/solr – maps the created volume to a directory in the container where the search index files, permission configuration, and log files will be stored,
• --add-host host.docker.internal:host-gateway – allows the container to reach services running on the host machine under the name host.docker.internal,
• webconbps/search:2026.2.2.121 – the image the container is started from; make sure to choose the correct version matching the WEBCON BPS version here,
• --entrypoint /bin/sh together with the argument -c "/opt/bps-solr/scripts/run-precreate-cores.sh" – the path to the script that initializes the Solr index structures. This script must be passed the first time the container is started so that the indexes can be created. It can always be passed, since on subsequent container starts the script detects existing indexes and skips recreating them.

6. The running container can be viewed under the Containers tab.

7. The Solr service will be available on this computer at http://nbdemo:8983/solr (where nbdemo is the name of the computer running Docker Desktop).

Creating the SQL databases

1. Download the WEBCON installer in the appropriate version (in this article, version 2026.2.2.121).

2. Run the installer and, after accepting the license, select the New WEBCON installation installation mode.

3. Next, select the Standalone environment type. In the System verification step, select the Next option, and in the Component selection step, select Skip.
   All components will be run from Docker images, and the installer will be used solely to create and configure the database.

4. In the following installer steps: Database creation parameters, Configuration database creation, Process database creation, Attachment database creation, proceed the same way as with a standard WEBCON installation.
   It is recommended to copy the name of the configuration database, as it will be needed when starting the Portal and Service containers.

5. In the Portal address configuration step, enter the address at which, according to the infrastructure plan, the BPS Portal will be made available. In the example described here, WEBCON BPS Portal will be available through a reverse proxy at the external address: https://nbdemo.webcon.pl:48440.
   Enter the Portal address here according to your infrastructure plan and select Next.

6. In the Administrative account step, enter and remember the password for the administrative user, who, after logging in to Designer Studio, will be able to complete the configuration of the WEBCON BPS installation.

7. The last step is Search Server address. In this step the installer must perform two actions: change the default user passwords in Search Server, and register this Search Server instance in the configuration database.
   To do this, in the Connect to field select the Default Search Server installation in a container option.
   Then enter the address of the Search Server container. In the example discussed here, this address is: http://nbdemo:8983/solr/.
   Also provide the passwords to be set for the Solr and WEBCON_BPS users.

Note: the Solr user is the administrator of this Solr instance. Make sure not to lose its password, as it is not stored anywhere else.

While performing this step, the Search Server container must be running, since the installer will connect to it in order to change the passwords and verify that the container’s contents are correct.

Docker network and environment variable files

The Portal, Service, and reverse proxy containers communicate with each other by host name, so they must operate on a shared Docker network. Create it before starting the containers:

docker network create webcon_net

In the following steps, the containers are given the following host names on this network: Portal – webcon, Service – webcon_service, reverse proxy – caddy_proxy.

Container configuration is passed via environment variable files. These are exactly the same values that can be set using the appsettings.json file in a standard WEBCON installation. Prepare three files in the current folder:

• user.env — a shared file with database connection details, used by both the Service and the Portal. Replace <SERVER>, <DBNAME>, <USER>, and <PASS> with your own values; for <DBNAME>, provide the name of the configuration database copied during database creation:

ConnectionStrings__ConfigDb=Server=<SERVER>;Database=<DBNAME>;User ID=<USER>;Password=<PASS>;Trust Server Certificate=True;

ConnectionStrings__LogsDb=Server=<SERVER>;Database=<DBNAME>;User ID=<USER>;Password=<PASS>;Trust Server Certificate=True;

Serilog__MinimumLevel__Default='Information'

Keep in mind that the container is not part of a domain, so it is necessary to define a database user name and password as an alternative to the more commonly used domain-based login.

• service_env.env — Workflow Service container variables:

STARTUP_MODE=service

ExternalWebService__Port=58002

ExternalWebService__LicenseServicePort=8002

Kestrel__Endpoints__Http__Url=http://*:48442

modulesOrchestration__webconWorkflowServicePort=48443

modulesOrchestration__serviceModuleRunnerPort=48450

DOTNET_gcServer=1

DOTNET_GCDynamicAdaptationMode=1

ASPNETCORE_FORWARDEDHEADERS_ENABLED=True

Service__Config__InitServiceRoles__BasicFeatures=true

Service__Config__InitServiceRoles__LicenseService=true

• portal_env.env — Portal container variables:

STARTUP_MODE=portal

Kestrel__Endpoints__Http__Url=http://*:48441

DOTNET_gcServer=1

DOTNET_GCDynamicAdaptationMode=1

DataProtection__ApplicationName='bps_container'

ASPNETCORE_FORWARDEDHEADERS_ENABLED=true

Meaning of the most important variables:

• STARTUP_MODE – the role the container should start in (portal or service),
• ConnectionStrings__ConfigDb, ConnectionStrings__LogsDb – connection strings for the configuration database and the logs database,
• Kestrel__Endpoints__Http__Url – the address and port on which the HTTP server in the container listens (48441 for the Portal, 48442 for the Service),
• modulesOrchestration__webconWorkflowServicePort – the port on which the Service exposes the workflow service,
• modulesOrchestration__serviceModuleRunnerPort – the port used for communication with the modules started by the Service,
• ExternalWebService__Port, ExternalWebService__LicenseServicePort – the ports for the external service and the license service,
• ExternalWebService__Host – the host name under which the Service is visible to the other components (passed directly in the docker run command),
• DataProtection__ApplicationName – the application name for the ASP.NET Data Protection mechanism; all Portal containers in this installation must have the same value,
• ASPNETCORE_FORWARDEDHEADERS_ENABLED – handling of headers passed by the reverse proxy,
• Serilog__MinimumLevel__Default – the logging level.

If the containers need to resolve host names from the corporate network (e.g. the name of the SQL server), add the --dns <DNS server address> parameter to the docker run commands.

Creating the Workflow Service container

1. The Workflow Service and BPS Portal container images are built on Windows Server Core Docker images. Because of this, just as before, Docker Desktop must be switched to Windows container mode.

2. Make sure the service_env.env and user.env files are prepared as described in the previous section and are located in the current folder.

3. Start the container by entering the following command in CMD:

docker run -d --name webcon_service_container --hostname webcon_service --network webcon_net --isolation=process -p 48442:48442 -p 48443:48443 -p 48450:48450 -e ExternalWebService__Host=webcon_service -e ServiceName=webcon_service -e Hostname=webcon_service --env-file service_env.env --env-file user.env webconbps/bootstrapper:2026.2.2.121-windowsservercore-ltsc2022

where:

• -d – runs the container in the background,
• --name webcon_service_container – the container name,
• --hostname webcon_service – the container’s host name; the Service is visible to the Portal under this name on the webcon_net network,
• --network webcon_net – connects the container to the previously created network,
• --isolation=process – the process isolation mode required for Windows Server Core containers,
• -p 48442:48442 -p 48443:48443 -p 48450:48450 – maps the host ports to the corresponding container ports (the port numbers must match those set in the service_env.env file),
• -e ExternalWebService__Host=webcon_service, -e ServiceName=webcon_service, -e Hostname=webcon_service – the host name and service name registered in the configuration database; they must match the value of the --hostname parameter,
• --env-file service_env.env --env-file user.env – the container will be started with the environment variables defined in these files,
• webconbps/bootstrapper:2026.2.2.121-windowsservercore-ltsc2022 – the image the container is started from; make sure to choose the correct version matching the WEBCON version here.

You can verify that the Service started correctly by opening http://localhost:48442/health. The running container can be viewed under the Containers tab, and the startup logs (including the selected STARTUP_MODE mode) can be viewed with the command:

docker logs webcon_service_container

In this configuration, ports 58002 (ExternalWebService__Port) and 8002 (ExternalWebService__LicenseServicePort) are not published on the host – within the webcon_net network, the Portal communicates directly with the Service. If these services need to be used by clients outside the container network, add the parameters -p 58002:58002 -p 8002:8002 to the docker run command.

Starting the BPS Portal container

1. The Portal container must be started after the Service container.

2. As with the Service, before starting the container prepare the portal_env.env and user.env files (the same user.env file used by the Service).

3. The Portal uses a hotfolder directory for processing files uploaded by users. To make sure data is not lost when the container is shut down, create a volume for it:

docker volume create hotfolder

4. Start the container using the command:

docker run -d --name webcon_portal_container --hostname webcon --network webcon_net --isolation=process -p 48441:48441 -v hotfolder:C:/hotfolder -e ServiceName=webcon -e Hostname=webcon --env-file portal_env.env --env-file user.env webconbps/bootstrapper:2026.2.2.121-windowsservercore-ltsc2022

where:

• -d – runs the container in the background,
• --name webcon_portal_container – the container name,
• --hostname webcon – the container’s host name; this name will be used in the reverse proxy configuration,
• --network webcon_net – connects the container to the same network the Service is running on,
• --isolation=process – the process isolation mode required for Windows Server Core containers,
• -p 48441:48441 – maps host port 48441 to container port 48441. This port must match the port set in the Kestrel__Endpoints__Http__Url variable in the portal_env.env file,
• -v hotfolder:C:/hotfolder – maps the volume to the hotfolder directory in the container,
• -e ServiceName=webcon -e Hostname=webcon – the host name registered in the configuration database,
• --env-file portal_env.env --env-file user.env – the container will be started with the environment variables defined in these files,
• webconbps/bootstrapper:2026.2.2.121-windowsservercore-ltsc2022 – the image the container is started from; this is the same image as for the Service – the container’s role is determined solely by the STARTUP_MODE variable.

Preparing the reverse proxy container for the Portal

Running the Portal in a container is often intended to make it easy to scale the web application by starting additional containers. In such a configuration, the Portal container is usually not exposed directly to users, but instead requires the use of a load balancer.

In the test installation described here, this configuration will be simulated by creating a container with a reverse proxy server for the Portal. Any server with this functionality can be used. This article uses the Caddy server, running on a Windows-based image.

The Caddy server container can be prepared as follows:

1. Create a Caddy configuration file named Caddyfile with the content below. Remember to replace the localhost address with the address of your own environment, while the host name and port that the reverse proxy points to must match the previously created Portal container (--hostname webcon, port 48441):

{

https_port 48440

}

https://localhost:48440 {

header {

X-Content-Type-Options nosniff

X-Frame-Options SAMEORIGIN

-Server

}

reverse_proxy {

to webcon:48441

stream_timeout 24h

stream_close_delay 5m

}

tls C:\etc\caddy\cert.pem C:\etc\caddy\key.pem

}

The stream_timeout and stream_close_delay parameters are important for correctly handling long-lived Portal connections (e.g. notifications). The X-Content-Type-Options and X-Frame-Options headers improve application security, while -Server removes the header that identifies the server.

2. The reverse proxy uses the HTTPS protocol. For the address served by the reverse proxy to be trusted, a trusted certificate for the test computer’s address must be used. To do this, place the cert.pem and key.pem certificate files in the current folder.

Create a Dockerfile with the Caddy image, with the following content:

FROM caddy:windowsservercore-ltsc2022

COPY Caddyfile /etc/caddy/Caddyfile

COPY cert.pem /etc/caddy/cert.pem

COPY key.pem /etc/caddy/key.pem

3. Next, build the Caddy image using the command:

docker build -t caddy/reverse.proxy .

4. Start the container using the command:

docker run -d --name caddy_proxy --hostname caddy_proxy --network webcon_net --isolation=process -p 48440:48440 caddy/reverse.proxy

The reverse proxy container must be connected to the same webcon_net network the Portal is running on – only then will the webcon name from the Caddyfile be resolved correctly.

Environment configuration

The architecture of the configured solution is based on the following components:

• Reverse proxy (Caddy) – https://nbdemo.webcon.pl:48440/
• Portal – http://nbdemo.webcon.pl:48441/
• Workflow Service – http://nbdemo.webcon.pl:48442/
• Search Server (Solr) – http://nbdemo:8983/solr

Ports used:

Accordingly, to start the Portal running in a container, open the link: https://nbdemo.webcon.pl:48440/.

Below is a list of steps to complete the configuration of the installed WEBCON platform. These are configuration steps required for every installation, not only one performed in Docker containers.

1. Log in to the WEBCON Portal, entering the password of the administrative user that was provided during database creation.
2. Install Designer Studio from the user menu in the Portal.
3. Log in to Designer Studio, entering the administrative user’s password.
4. Activate the (subscription) licenses in Designer Studio. Please refer to the guide on license activation.
5. Configure synchronization of the user list (e.g. from Microsoft Entra ID) and force it to run.
6. Configure an authentication provider other than Admin access, e.g. Microsoft Entra ID.
7. After the user list has been synchronized, assign licenses to the appropriate users.
8. Grant global permissions to the users in your organization who will manage the installation’s configuration.
9. After completing these steps and verifying that they work correctly, you can disable the Admin access authentication provider.