Deploying to Linux

Deploying on Linux with .NET 6

With .NET 6, Harmony Core services can run on Windows and Linux servers, including Windows Subsystem for Linux (WSL 2). These services can then access Synergy data and code on the same server or on any Windows, Unix/Linux, or OpenVMS system supported for traditional Synergy (although xfServer is required to access Synergy data on a different server).

In all cases, even when Harmony Core services will be deployed to a Linux system, you'll develop these services on Windows with Visual Studio 2022. For testing and debugging, you can deploy to a Linux machine or a WSL 2 system and then debug the services remotely from Visual Studio 2022.

Overview

The following are the basic steps for Harmony Core development and deployment for Linux:

Develop the Harmony Core application using Visual Studio 2022 on a Windows development machine. Any existing Harmony Core 3.x projects must be updated to .NET 6, and Windows-specific code (e.g., Windows paths in configuration files) must be removed. See  Upgrading from Harmony Core 3.x and Preparing for Linux Deployment below.
To debug and test the application, deploy it to a Linux machine or a WSL 2 system and use Visual Studio’s remote debugging functionality. See Publishing, Deploying, and Starting Your Service  and Debugging a Harmony Core Service on Linux below for more information. See Setting Up a WSL 2 System below for information on WSL 2.
When you're finished debugging and testing, deploy the application to the production Linux system. See Publishing, Deploying, and Starting Your Service  below.

Requirements

The development machine must have the tools listed in Required Tools. Important: Be sure to use the latest version of the Harmony Core Solution Upgrade Tool and CodeGen.

The server system (a Linux machine or WSL 2 Linux distribution) must have the following:

Linux kernel 3.15 or higher
Synergy/DE 12 or higher or the version 12 REV11 licensing upgrade package (LUP) to provide Synergy/DE REV11 licensing for the system. See Synergy/DE Licensing in the Synergy/DE documentation for more information.

Upgrading from Harmony Core 3.x and Preparing for Linux Deployment

Harmony Core solutions created with version 3.x of Harmony Core must be upgraded to .NET 6 before they can be built and published for Linux deployment. To do this, use the Harmony Core Solution Upgrade Tool’s “upgrade-latest” command. See Updating a Harmony Core Solution.

Additionally, before you can deploy to Linux you must remove any Windows-specific code, such as Windows paths in configuration files. Note that Harmony Core code and files supplied by or generated with Harmony Core templates do not have Windows-specific code.

Publishing, Deploying, and Starting Your Service

To publish and deploy a Harmony Core service to a Linux system and then start it,

Open a Windows command prompt and move to the project directory for the hosting program. For example, if you used the harmonydemo template to create the demo solution (as instructed in Tutorial 1: Creating a Demo Service), or if you used the harmonycore template (as instructed in Tutorial 2: Building a Service from Scratch), move to the Services.Host directory.
Set the SolutionDir environment variable to the solution directory for the Harmony Core solution. For example, if you open a Windows command prompt in the solution directory, the following will set SolutionDir to that location:
```
set SolutionDir=%CD%\  
```
Move to the directory for the hosting program, and then use the dotnet publish command to publish the project, specifying --runtime linux-x64 (or -r linux-x64) as the target platform. For example, if you opened a Windows command prompt in the solution directory for the demo solution in the previous step, the following moves to the project directory for the hosting program (Services.Host) and publishes to the specified directory:
```
cd Services.Host 
dotnet publish -c Debug   -r linux-x64 -o ..\distribution\linux\debug  
```
This command builds the application in debug mode and places all the resulting binaries, content files, and binaries for dependencies in a specified folder. When the publish is complete, the specified folder contains everything the application needs to run on another system (except REV11 licensing). This includes the .NET and Synergy runtimes. See Microsoft documentation on the publish command for more information.

NOTE: When you create the Harmony Core solution from the harmonydemo or harmonycore template, the solution’s "Solution Items" folder will contain an example publish script, Publish.bat. This script can be set up to build and publish the solution, zip up all the needed files, and put the zip file in a location of your choosing. See the comments in the script file for more information.
Once your Harmony Core application has been published, you can either copy the files created by the publish to a folder on the Linux system, or if you are using a WSL 2 system, you can instruct the WSL 2 system to access the published application on the Windows system (see step 8 below for an example).
Set up SSL certificates for the application (see  Configuring SSL certificates  below), and configure any environment variables the application might need, such as environment variables for the SSL certificate and ports the service will listen on, which can be set with these environment variables:
- ASPNETCORE_Kestrel__Certificates__Default__Path
- ASPNETCORE_Kestrel__Certificates__Default__Password
- ASPNETCORE_URLS
- ASPNETCORE_HTTPS_PORT
For example, for the demo service published in step 3 you could create a "setup" file like this:
```
$ cd ~ 
$ cat > setup 
export ASPNETCORE_URLS="https://*:8086;http://*:8085" 
export ASPNETCORE_HTTPS_PORT=8086 
export ASPNETCORE_Kestrel__Certificates__Default__Path=/home/myuser/.aspnet/https/Services.Host.pfx 
export ASPNETCORE_Kestrel__Certificates__Default__Password="pswdformycert" 
```
Note that you can set an HTTP endpoint for a Harmony Core service, but it will redirect to the HTTPS endpoint.
If you copied the published files to the Linux system, make sure the hosting program (Services.Host) and any Traditional Bridge launch script files are marked as executable. With WSL 2, if the files reside on the host system (i.e., not in the WSL 2 environment), you may need to make sure Windows permissions for the file permit access to and execution of the files.
If your Harmony Core service accesses data files, make sure the service has access to these files. For example, if you published the demo service, you could copy all the data files it accesses (customers.ism/.is1, orders.ism/.is1, etc.) to the directory that contains Services.Host (e.g., c:\harmonycore\tut1\distribution\linux\debug, if that is what you specified in step 3 above).
If your Linux system has been set up with REV11 licensing (for example, by installing Synergy/DE and running the setsde script as described in Installing Synergy/DE for Licensing on WSL 2 below), you should now be able to start and access your Harmony Core service. If you published and deployed the demo service, for example, you can start it by running Services.Host. If Services.Host is in the c:\harmonycore\tut1\distribution\linux\debug directory on the Windows machine, for example, run it from that directory:
```
$ cd /mnt/c/harmonycore/tut1/distribution/linux/debug 
$ ./Services.Host 
```
As the self-hosting program starts, you should see output like this:
```
Hosting environment: Production 
Content root path: /mnt/d/hc/debug/ 
Now listening on: http://localhost:8085 
Now listening on: https://localhost:8086 
Application started. Press Ctrl+C to shut down. 
```
You can then open a browser on the Windows host machine and access it from the specified locations. For instance, if the service is running on a WSL 2 system and you set the HTTPS port to 8086, enter the following in the address bar of a browser window opened on the host Windows machine:
```
https://localhost:8086 
```
If you published and deployed the Harmony Core demo service, you should see the default home page for the demo service:

Debugging a Harmony Core Service on Linux

To debug, you’ll use Visual Studio’s Attach to Process feature as documented in Remote debugging in the Synergy/DE documentation. The following summarizes the procedure documented in that topic and provides some example steps you can follow if you’ve published the Harmony Core demo service as described in Publishing, deploying, and starting your service above.

For more information on debugging with Visual Studio, see Visual Studio documentation, and note that Visual Studio documentation on attaching to processes includes information on features that are not supported for Harmony Core services—features such as attaching to a process running on Azure App Service, attaching to a process running in a Docker container, and reattaching to a process.

Make sure your Windows development machine and the Linux system meet the requirements listed in Remote debugging in the Synergy/DE documentation.
In Visual Studio, open the solution, project, or source file(s), and set breakpoints as needed.
If you are debugging a problem that occurs when the service starts, set the WAIT_FOR_DEBUGGER environment variable on the Linux system. Set it to any value. For example:
```
$ export WAIT_FOR_DEBUGGER=1 
```
On the Linux system, start the Harmony Core service. For example, if you published and deployed the Harmony Core demo service as shown in the example steps in Publishing, Deploying, and Starting Your Service above, move to the directory with the published service and run Services.Host:
```
 $ cd /mnt/c/harmonycore/tut1/distribution/linux/debug 
 $ ./Services.Host 
```
As the self-hosting program starts, you should see output like this:
```
Hosting environment: Production 
Content root path: /mnt/d/hc/debug/ 
Now listening on: http://localhost:8085 
Now listening on: https://localhost:8086 
Application started. Press Ctrl+C to shut down. 
```

In Visual Studio, select Debug > Attach to Process.

In the “Attach to Process” dialog, select the connection type and then the connection target (the Linux system the service is running on). For the Connection type field, select one of the following:
- For a service on WSL 2, select Windows Subsystem for Linux (WSL).
- For a service on a remote Linux machine, select SSH.
Click the Select button for the Attach to field. In the dialog that opens, select Managed (.NET Core for Linux) and click OK.
Click the Select button for the Attach to field. In the dialog that opens, select Managed (.NET Core for Linux) and click OK.
In the Available Processes area of the “Attach to Process” dialog, select the name of the process you want to debug. For example, for the Harmony Core demo service, select Services.Host.
Click Attach. Then select Debug > Start Debugging from the Visual Studio menu to start debugging.

Configuring SSL Certificates

SSL certificates are required for Harmony Core services. This is because the default Harmony Core services are available only via HTTPS. (There is an HTTP endpoint for Harmony Core services, but it redirects to the HTTPS endpoint.)

For debugging and testing deployments, you can use self-signed certificates. See Using self-signed SSL certificates below.
For a production deployment, you’ll need to use a real SSL certificate from a trusted vendor, and you’ll need to use a secure method to specify the password for the certificate (e.g., AppSecrets or Azure Key Vault Service).

Using Self-Signed SSL Certificates

With .NET 6 development on Windows, the .NET SDK enables you to create a self-signed developer certificate and register that certificate as trusted for the development system. When developing a Harmony Core service for Linux, you must create and trust a self-signed certificate, and you must configure the Harmony Core service (which is an ASP.NET application) to use the certificate:

On the Windows host machine, create a self-signed certificate. For example, you can use the dotnet dev-certs command at a Windows PowerShell prompt:
```
dotnet dev-certs https -ep $env:USERPROFILE\.aspnet\https\Services.Host.pfx -p pswdformycert  
dotnet dev-certs https –-trust 
```
If your Harmony Core service will be deployed to a Linux machine (as opposed to a WSL 2 system), copy the self-signed certificate to the Linux machine. If your service will be deployed to a WSL 2 system, either copy the self-signed certificate to a directory on the WSL 2 system, or in the next step configure the service to access the certificate on the host system as shown in the example for the next step.
Configure the Harmony Core service to use the certificate. For example, you can do this by setting the following environment variables on the Linux system. Note that the path in the example specifies a location on the C: drive of the Windows host machine. (WSL 2 systems have access to drives, directories, and files on the host system.)
```
$ export ASPNETCORE_Kestrel__Certificates__Default__Path=/mnt/c/Users/myuser/.aspnet/https/Services.Host.pfx  
$ export ASPNETCORE_Kestrel__Certificates__Default__Password="pswdformycert" 
```

Setting Up a WSL 2 System

For testing and debugging, you can deploy test builds to a WSL 2 system. Remote debugging is supported for Harmony Core services running on remote Linux systems, including WSL 2 systems (see Debugging a Harmony Core Service on Linux above).

Installing a WSL 2 Linux System

To use WSL 2 for Harmony Core, the windows machine that will host WSL 2 must meet WSL 2 system requirements (see WSL 2 documentation). It must have either Windows 11 or Windows 10 version 1903, Build 18362 or later, and Hyper-V must be enabled.

For information on setting up WSL 2, see Microsoft documentation (e.g., Install Linux on Windows with WSL). It takes just a few steps to install the default Ubuntu distribution:

Open a Windows command prompt as an administrative user. Then enter the following command:
```
C:\> wsl --install 
```
This will start the installation process.
When prompted by the installation to reboot the system, reboot.
After rebooting, the installation will continue, and you will be prompted to enter a username and password for a new Linux account. Enter a username and password for the new Linux account, and be sure to note both for later use.

You should now have a working Ubuntu Linux system, which you can access from the Windows Start menu. For example, if you installed the default Ubuntu distribution, click the Windows Start button, type Ubuntu, and select the Ubuntu on Windows app.

Note that before you can run a Harmony Core service on the system, you must establish Synergy/DE REV11 licensing for the system by installing either Synergy/DE 12 or higher or the version 12 REV11 licensing upgrade package (LUP). See the next section, Installing Synergy/DE for Licensing on WSL 2, for more information and for example steps for installing Synergy/DE. For information on licensing, see Synergy/DE Licensing in the Synergy/DE documentation.

Installing Synergy/DE for Licensing on WSL 2

Before you can run a Harmony Core service on a Linux system, you must set up REV11 licensing for the system. You can do this by either installing Synergy/DE 12 or higher or installing the version 12 REV11 licensing upgrade package (LUP).

The following are sample steps for installing Synergy/DE on the default Ubuntu WSL 2 system. For complete Synergy/DE installation information, see the Unix installation instructions for Synergy/DE, which are available at https://www.synergex.com/docs/install/Title_install.htm.

Open the command prompt for your WSL 2 system. For example, if you installed the default Ubuntu system, click the Windows Start button, type Ubuntu, and select the “Ubuntu on Windows” app.
At the WSL 2 system command prompt, make a temporary folder and move to it. For example:
```
$ cd ~ 
$ mkdir tmp 
$ cd tmp 
```
Download the Synergy/DE distribution you want to install. For example, the following command downloads 64-bit Synergy/DE version 2.1.1.3278:
```
$ wget --quiet https://s3.amazonaws.com/media.synergex.com/prod/428SDE1211-3278.a -O installer.a
```
Switch to the root account for the WSL 2 system:
```
$ su 
Password: <rootpassword>  
```
If you have a Synergy license server installed on your Windows PC, configure your Synergy license manager to forward license requests to your Windows host system. (This is the recommended configuration if you are working on a laptop computer or working from home or some other location other than your office.) If you do not have a Synergy license server installed on your Windows PC, configure your Synergy license manager to forward license requests to a Windows license server on some other system on your network. (This configuration is recommended only if your PC is in a fixed location in an office where a Synergy license server exists on the network.) In any case, you will need to determine the DNS name or TCP/IP address of the license server system and verify that your Linux environment can communicate with the license server—e.g., by pinging the license server.

To determine the TCP/IP address of your host PC, open a command prompt on the PC and type the following command:
```
$ ipconfig  
```
You should see information about your PC's network adapters (there may be several). For example, for WSL, look for the adapter named Ethernet adapter vEthernet (WSL)—e.g.,
```
Ethernet adapter vEthernet (WSL):  
Connection-specific DNS Suffix . :  
Link-local IPv6 Address . . . . . : fe80::c8f8:3594:9ff1:8c0c%36 
IPv4 Address. . . . . . . . . . . : 172.25.192.1  
Subnet Mask . . . . . . . . . . . : 255.255.240.0  
Default Gateway . . . . . . . . . :  
```
Now use a ping command to verify that you have access to the PC via its DNS name or IP V4 address. If you know the name of the PC you can try using it. For example:
```
$ ping –c3 mypc 
```
Or try the address. For example:
```
$ ping -c3 172.25.192.1  
```
You should see a response like this:
```
PING 172.25.192.1 (172.25.192.1) 56(84) bytes of data.   
64 bytes from 172.25.192.1: icmp_seq=1 ttl=128 time=0.215 ms 
64 bytes from 172.25.192.1: icmp_seq=2 ttl=128 time=0.239 ms 
64 bytes from 172.25.192.1: icmp_seq=3 ttl=128 time=0.248 ms  
--- 172.25.192.1 ping statistics --- 
3 packets transmitted, 3 received, 0% packet loss, time 2077ms 
rtt min/avg/max/mdev = 0.215/0.234/0.248/0.013 ms 
```
Make a note of the DNS name or TCP/IP address, you will need it later when you configure your Synergy license server.
Extract the installation files. For example:
```
# umask 0 
# cpio –ivBdum < insataller.a 
```
You should see a list of files being extracted from the cpio archive.
Now execute the Synergy installation script:
```
# ./install.sde 
```
We recommend installing Synergy to a version-specific folder such as /synergy/<version>. For example, for version 12.1.1.3278, you could create a /synergy/1211_3278 directory. You will need to manually enter this information during the installation.
You can now delete the installation files by deleting the tmp folder you created in step 2, and you can exit from the root account:
```
# rm –rf tmp
# exit 
$ 
```
To use Synergy licensing, you will need to enable the new Synergy/DE environment by executing the setsde script, which is in the synergyde directory. For example, move to the synergyde directory and enter the following:
```
$ ./setsde  
```
Make sure Synergy licensing is working for the WSL 2 system by using the lmu utility:
```
$ lmu  
```

You should see something like the following, though your list of licensed products may be shorter:

   For Linux X64 (428) 
   Forwarding To: 55.5.5.555:5555 with backup LICSERVER:5555
   Licensee Name: ORGNAME-LICSERVER 
   Registration String: XXXXXXX-XXXXXXX-XXXXXXX-XXXXXXX-XXX 
   
   Licensed Products: 
   2 999    RUN10   100 20221114 20311112 
   0 999    WRUN10   30 20221114 20311112 
   0 999    LMK10     1 20221114 20311112 999 
   2 999    XFSV10   30 20221114 20311112 
   0 999    XFSP10   30 20221114 20311112 
   1 999    PSW10    30 20221114 20311112 
   1 999    PSDE10   30 20221114 20311112 
   0 999    RPTW10   30 20221114 20311112 
   0 999    BLS10     2 20221114 20311112 8 
   0 999    SDB10    30 20221114 20311112 
   0 999    SCOR10   30 20221114 20311112 
   0 999    SCOD10  999 20221114 20311112 
   2 999    SCSQ10   30 20221114 20311112 
   0 999    SCMY10   30 20221114 20311112 
   0 999    LMK10     1 20221114 20311112 998 
   0 999    LMK10     1 20221114 20311112 997 
   0 999    LCFG      1 20221114 20311112 1 
   1 999    SRUN10  999 20221114 20311112 
   0 999    PSW7     30 20221114 00000000 
   0 999    PSDE     30 20221114 00000000

You should now be able to deploy a Harmony Core service to this system. See Publishing, deploying, and starting your service above.

Provide feedback

Saved searches

Use saved searches to filter your results more quickly