Tutorial 1: Deploying your PowerServer project to production environment

In the Quick Start guide, we use the simplest scenario (all roles in one machine) to quickly get started with the PowerServer deployment; now in this tutorial, we will walk through the deployment process in a more production-like environment, using individual machines as the client, development PC, Web server, database server, and API server.

Important

For optimal runtime performance, it is highly recommended that the Web APIs should be published to a PowerServer that locates on the same LAN as the database server. If the database is not on the same network as the Web APIs, every request has to go a long way from PowerServer to the database, it is highly possible that there will be performance and security issues.

It is recommended that before you go through this tutorial you have a successful result with the Quick Start guide first, so that you have basic concepts of the whole deployment process.

Task 1: Setting up the client machine

Set up the client machine with the following OS and software:

  • Windows 10

  • Google Chrome

    This tutorial takes Google Chrome as an example. You can also use Firefox or the new Edge browser (Chromium-based).

Task 2: Setting up the database server

Preparations

In this tutorial, we will set up the salesdemo SQL Anywhere database server running in an independent machine.

Set up the database server with the following OS and software:

  • Windows Server 2019 (64-bit)

  • SQL Anywhere 17

    This tutorial takes SQL Anywhere database as an example. You can also install the other databases by following documentation from the vendor.

    Note that the SQL Anywhere database can only be connected through an ODBC driver. You will need to create the same ODBC data source in both the development PC and the API server. The data source in the development PC is for converting DataWindows to models, and the data source in the API server is for accessing data from the database. The following sections have detailed instructions for how to create the ODBC data source.

Configuring Windows Defender Firewall

If Windows Defender Firewall or any anti-virus tool is turned on, make sure to configure Windows Defender Firewall or the anti-virus tool to allow the database server port (2638 in this tutorial or any number have changed to) to go through, otherwise, connection errors will occur.

You would need to configure the firewall/anti-virus settings on the following servers:

  • Database server -- to allow the database server port (2638 in this tutorial)

  • API server -- to allow the API server port (5009 in this tutorial)

  • Web server -- to allow the FTP server port (21 in this tutorial) (this only affects the FTP connection during the app deployment, but not running of the app)

The following steps configure the firewall settings on the database server (you can take the same steps to configure for the other servers):

Step 1: Open Windows Defender Firewall and then click Advanced settings.

Step 2: Select Inbound Rules and then click New Rule.


Step 3: Create a new rule which allows connections through the database server port (2638 in this tutorial).


Starting the database

Step 1: Copy the database file (pbdemo2021.db) from the development machine (%Public%\Documents\Appeon\PowerBuilder 21.0\) to the database server.

Step 2: Start this database file on the salesdemo database server using SQL Anywhere Network Server (dbsrv17.exe).

The database server must be started as a network server (not personal server) in order to support network connections.

"C:\Program Files\SQL Anywhere 17\Bin64\dbsrv17.exe" -x tcpip(port=2638) -n salesdemo "C:\DB\pbdemo2021.db"

Task 3: Setting up the Web server

The installable cloud apps can be hosted in the following Web servers:

  • Windows IIS

  • Windows/Linux Apache HTTP Server

  • Windows/Linux Nginx

Read the section below according to the Web server type used in your environment.

IIS
Preparations

In this tutorial, we will set up a Web server and an FTP server running on the same IIS.

Step 1: Set up the Web server with the following OS and software:

Step 2: Configure the Windows Defender Firewall on the Web server to allow the FTP port (21 in this tutorial). The section "Configuring Windows Defender Firewall" has detailed instructions.

Installing Web Server (IIS)

Step 1: In Windows Server 2019, open Server Manager, and then select Add roles and features.

Step 2: In the Add Roles and Features Wizard, click Next several times until the Server Roles section displays.

Step 3: Click the check box of Web Server (IIS); and then click Add Features when asked whether to add features required for Web server.


Step 4: Make sure the check box of Web Server (IIS) is selected.


Step 5: Click Next until the Role Services section displays. Make sure the following role services are selected.

Select to enable the following services:

  • Default Document

  • Static Content

  • .NET Extensibility 4.7

  • Application Initialization

  • ASP.NET 4.7

  • ISAPI Extensions

  • ISAPI Filters

  • IIS Management Console

  • FTP Service

  • FTP Extensibility

    FTP Service & FTP Extensibility must be enabled if you want to create an IIS FTP site for transferring files from a remote development machine to the Web server.


Step 6: Click Next and then click Install.

After IIS is installed, a Default Web Site is automatically created.


Step 7: Open a Web browser and run the following URLs to access the Default Web Site.

http://localhost:80/

http://IP_Address:80/

TIP: to obtain the IP address, open a command prompt window and then type ipconfig<Enter>. Mark down the IP address as it is needed when you configure the Web server profile in PowerBuilder.

If the IIS welcome screen displays, the IIS website is working properly.


Also remember the physical path for Default Web Site which is C:\inetpub\wwwroot by default (or any other path you have changed to). This is where the application will be deployed, or the FTP site will point to.

Creating an IIS FTP site

In the previous section, if you have selected to enable FTP Service & FTP Extensibility, you can create an IIS FTP site to be used by the remote deployment.

Step 1: In the IIS Manager, right click Sites, select Add FTP Site.

Step 2: Specify a name for the FTP site, and set the physical path to the Web root of the IIS Web server (C:\inetpub\wwwroot in this tutorial). Click Next.


Step 3: Use the default port 21 (or specify a different port if you like). If no certificate is available, you can select No SSL. Use the default values for the other settings. Click Next.

For how to configure SSL on an IIS FTP site, refer to Configure an SSL-based FTP server.


Step 4: Select Anonymous and Basic authentication. Select All users or specify the users that are allowed to access the FTP site, and then select the Read and Write permissions. Click Finish.


The FTP site is created.


Step 5: Open a Web browser and run the following URL to access the FTP site.

ftp://IP_Address:21/

If the FTP root displays, then the FTP site is working properly.


Apache HTTP Server on Windows
Preparations

In this tutorial, we will set up a Web server running on Apache HTTP Server.

Step 1: Set up the Web server with the following OS and software:

Step 2: Configure the Windows Defender Firewall on the Web server to allow the port (21 in this tutorial). The section "Configuring Windows Defender Firewall" has detailed instructions.

Installing Apache HTTP Server

This tutorial will be ready by the time of GA release of PowerBuilder 2021.

Step 1: Select a binary package from https://httpd.apache.org/docs/current/platform/windows.html#down.

Step 2: ...

Nginx

In this tutorial, we will set up a Web server running on Nginx.

This tutorial will be ready by the time of GA release of PowerBuilder 2021.

Task 4: Setting up the development PC

Preparations

Set up the development machine with the following OS and software (install the software in the order listed):

  • Windows 10 (64-bit)

  • SQL Anywhere 17

  • PowerBuilder IDE 2021

    During installation, make sure to select the SQL Anywhere engine for the PowerBuilder demo database.

    The PowerBuilder demo database file for SQL Anywhere (pbdemo2021.db) will be installed to the %Public%\Documents\Appeon\PowerBuilder 21.0\ directory.


  • PowerBuilder Runtime 2021

  • PowerServer Compiler 2021

  • SnapDevelop 2021 (optional)

  • Google Chrome (optional)

Creating the ODBC data source

Database connection needs to be established between the development PC and the database server (for converting DataWindows to models), and between the API server and the database server (for retrieving data). Currently the SQL Anywhere database can only be connected through an ODBC driver, therefore, you will need to create the same ODBC data source in both:

  • the development PC, and

  • the API server

The following steps create an ODBC data source on the development PC that connects with the salesdemo SQL Anywhere database server (you can take the same steps to configure for the API server):

Step 1: Install SQL Anywhere 17.

Step 2: Create a 64-bit ODBC data source and name it as "SalesDemo DB". The data source name must be the same in both the development PC and the API server.

IMPORTANT: Make sure you use the 64-bit version of ODBC administrator to create the data source, because only the 64-bit ODBC data sources can be selected for the PowerServer project.

Step 3: Click Test Connection to ensure the connection settings are correct.



Creating a Web server profile for remote deployment

Step 1: Go to the development PC, select Windows Start | Appeon PowerBuilder 2021, and then right-click Example Sales App and select More | Run as administrator. The SalesDemo workspace is loaded in the PowerBuilder IDE.

Step 2: Select Tools>Web Server Profile from the PowerBuilder menu bar to open the Web Server Profile window.

Step 3: In the Web Server Profile window, click Add.

Step 4: Select Remote server, and then specify the settings for connecting with the FTP site.

In this tutorial, specify the following values (or any values you have changed to):

Server profile name: Any text, for example, Remote IIS Web Server.

Host: IP address or host name of the Web server, for example, 172.16.100.63.

Port: Port number of the IIS Web server, for example, 21.

User name: Windows user name.

Password: Windows user password.


Step 5: Click Test FTP Connection and make sure connection to the FTP server is successful.

Tip

In case connection errors occur, try the following to resolve:

  • Check if the Windows Defender Firewall on the FTP server allows the FTP port (21 in this tutorial) to go through.

  • Check if the port (21 in tutorial) is occupied by the other program.

  • Input a user name and password for logging to the FTP server, instead of using anonymous login.

  • Check if the user has read and write permissions to the FTP root.

Uploading the cloud app launcher and the runtime files to the remote server

Step 1: Select Tools>Upload Cloud App Launcher from the PowerBuilder menu bar.

Step 2: In the Upload Cloud App Launcher and Runtime window that appears, select Directly upload to the server and then select "Remote IIS Web Server" from the listbox.

Step 3: Keep the other settings as default and click Upload.


Step 4: When the upload is finished, go to the Web server and verify the "CloudAppPublisher" folder exists under the path for the IIS website (C:\inetpub\wwwroot in this tutorial).

Modifying and re-deploying the PowerServer project

The following modifications are made to the PowerServer project created in the Quick Start guide. If you have not created a PowerServer project yet, please follow the instructions in the Quick Start guide to create one.

Step 1: Select the profile for the remote server (instead of the local server).

On the Client Deployment tab of the PowerServer project painter, select "Directly deploy to the server" and "Remote IIS Web Server" in the Deployment mode section.

The "Remote IIS Web Server" profile is created in the section Creating a Web server profile for remote deployment.


Step 2: Specify the Web API URL. The Web API URL is used by the installable cloud app to call the Web APIs.

On the Web APIs tab of the PowerServer project painter, specify the Web API URL, for example, http://172.16.100.71:5009. This indicates that the installable cloud app will call the Web APIs running on the server at http://172.16.100.71:5009.

Important

  1. Make sure the Web API is running at the same IP address (or host name) and port number. For how to start the Web API, see the next section.

  2. If the IP address and port number of the API server are changed later, you will need to modify the settings here and then deploy the project again (using the "Build & Deploy PowerServer Project" option).


Step 3: Select the ODBC data source.

At the bottom of the Web APIs tab of the PowerServer project painter, click the Database Configuration button.

In the Database Configuration dialog, click New in the upper part to create the database connection that will be used by the deployment.

Configure the database connection with the following settings:


Make sure the check box for the database cache you created just now is selected.

Then select the database cache you created just now to map with the "sqlca" transaction object.


Step 4: Save the PowerServer project settings.

Step 5: Build and deploy the PowerServer project (using the "Build & Deploy PowerServer Project" option) for the changes to take affect.

When the deployment is finished, go to the Web server and verify that the "pstutor_salesdemo_asa" folder exists under the Web root for the IIS Web server (C:\inetpub\wwwroot in this tutorial).

Step 6: Go to the specified location (C:\Users\appeon\source\repos in this tutorial) and copy the PowerServer solution folder to the API server.

Task 5: Setting up the API server

Preparations

In this tutorial, we will set up a Web API server running in an independent machine.

This tutorial starts the Web APIs in the debug mode, you can also deploy the Web APIs in a release mode and host it in a more secure and manageable environment such as Docker Container, IIS, Kestrel etc. as described in tutorial 2, 3, & 4.

Step 1: Set up the API server with the following OS and software:

  • Windows Server 2019 (64-bit)

  • SQL Anywhere 17

  • SnapDevelop 2021

Step 2: Make sure the API server can connect with the NuGet site: https://www.nuget.org (for installing PowerServer NuGet packages) and the following Appeon sites: https://apips.appeon.com, https://apipsoa.appeon.com, https://apipsinfo.appeon.com, and https://api.appeon.com (for validating the PowerServer license).

Step 3: Configure the Windows Defender Firewall on the API server to allow the API server port (5009 in this tutorial or any number you want to change to). The section "Configuring Windows Defender Firewall" has detailed instructions.

Creating the ODBC data source

Database connection needs to be established between the development PC and the database server (for converting DataWindows to models), and between the API server and the database server (for retrieving data). Currently the SQL Anywhere database can only be connected through an ODBC driver, therefore, you will need to create the same ODBC data source in both:

  • the development PC, and

  • the API server

Step 1: Install SQL Anywhere 17.

Step 2: Create a 64-bit ODBC data source and name it as "SalesDemo DB". The data source name must be the same in both the development PC and the API server. The data source should connect with the salesdemo SQL Anywhere database server (which is set up in Task 2: Setting up the database server).

IMPORTANT: Make sure you use the 64-bit version of ODBC administrator to create the data source, because only the 64-bit ODBC data sources are supported by PowerServer.

Step 3: Click Test Connection to ensure the connection settings are correct.



Publishing the Web APIs

Step 1: Copy the PowerServer Web API solution from the development PC (C:\Users\appeon\source\repos in this tutorial) to the API server.

Step 2: Double click PowerServerApp.sln to launch the solution in SnapDevelop. Log in to SnapDevelop if required.

The PowerServer Web API solution will connect with the NuGet site (https://www.nuget.org) to download and install the required packages from the NuGet site.

Clicking Run from the SnapDevelop toolbar can start the Web APIs in the debug mode.

However, for optimal performance, it is recommended that you publish the Web APIs to a dedicated server and run the Web APIs in the release mode as described in