Tutorial 2: Hosting Web APIs in Docker Containers

The PowerServer Web API is an ASP.NET Core app; it can be hosted and deployed like any other ASP.NET Core app described in https://docs.microsoft.com/aspnet/core/host-and-deploy/?view=aspnetcore-3.1.

This tutorial takes Docker as an example to show you how to publish and host the Web APIs in a Docker Container; it will reuse part of the configurations in the Quick Start and Tutorial 1, thus, it is strongly recommended that you have completed the Quick Start guide and Tutorial 1 first.

Task 1: Setting up Docker

Setting up a docker host (Docker Engine)


The docker host is where the docker image is built and the docker container is run. The ServerAPIs project will be built and published as a docker image first, and then the docker image will be run as a docker container. The Web APIs are actually hosted and run in the docker container.

Step 1: Set up a docker host (also called Docker Engine in the SnapDevelop IDE).

To set up a docker host/Docker Engine, refer to https://docs.docker.com/engine/install/.

In this tutorial, a Docker Engine has already been set up in a Linux server (suppose its IP address and port number are 172.25.100.20:2375).

Write down this information as it will be required when you build the ServerAPIs project as a docker image (in the later section Publishing Web APIs to Docker).

Step 2: Make sure the docker host machine can connect to 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).

If the docker host machine connects to Internet via a proxy server, refer to Configure Docker to use a proxy server for detailed instructions.

Setting up a docker registry


A docker registry is the repository where the docker image is published and shared. You may choose from the following registries:

  • Docker Hub -- Docker's official registry, it is the default registry when you install Docker. You can connect to the public registry (hub.docker.com:443) that anyone can use or a your own private registry. You will be required to log into Docker Hub before you can store the image. For more about Docker Hub, refer to https://docs.docker.com/docker-hub/.

  • A self-hosted Docker Registry -- Your own registry created using the open-source Docker Registry. For more about Docker Registry, refer to https://docs.docker.com/registry/.

Step 1: Set up a docker registry.

In this tutorial, a self-hosted Docker Registry has already been set up in a Linux server (suppose its IP address and port number are 172.25.100.20:5000).

Write down this information as it will be required when you build and publish the ServerAPIs project as a docker image (in the later section Publishing Web APIs to Docker).

To know more about Docker, we recommend you start by understanding the Docker Architecture.

Task 2: Setting up the database server

Preparations

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

In this tutorial, we will set up a database server with the PBDemo PostgreSQL database running in an independent machine.

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

  • Windows Server 2019 (64-bit)

  • PostgreSQL 12

Step 2: Configure Windows Defender Firewall on the database server to allow the database server port (5432 in this tutorial or any port number you choose). The section "Configuring Windows Defender Firewall" has detailed instructions.

Starting the database

Step 1: Go to the development PC where PowerBuilder IDE is installed, copy the database file (pbpostgres2021.dmp) from the PowerBuilder demo installation folder (%Public%\Documents\Appeon\PowerBuilder 21.0\) to the database server.

If you have not set up the development PC according to Preparations in Task 3: Setting up the development PC, there may be no pbpostgres2021.dmp file in the demo installation folder.

Step 2: Restore and run the database in the management tool for PostgreSQL.

  1. Select Windows Start menu | PostgreSQL 12 | pgAdmin 4.

    pgAdmin 4 is a Web application. If pgAdmin 4 cannot run in Internet Explorer (the default Web browser in Windows Server 2019), you can install and try Google Chrome.

  2. Expand Servers | PostgreSQL, right click Databases, and select Create | Database.


  3. Input PBDemo in the Database field and click Save.


  4. Right click PBDemo that was just created, and select Restore.


  5. Select the pbpostgres2021.dmp file and click Restore.


    After the database file is restored, you will be able to view the following schemas:


  6. Open the pg_hba.conf file in a text editor and add the following line. The pg_hba.conf file is located in %PostgreSQL%\12\data. This enables the database server to allow remote connections.

    host    all             all             0.0.0.0/0               md5

Task 3: 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)

  • PostgreSQL 12

    During installation, make sure the Command Line Tools component is selected to install, and specify and write down the following information:

    Data Directory: C:\Program Files\PostgreSQL\12\data by default

    Database Superuser: postgres by default

    Password for Database Superuser: (this password is set during installation) postgres in this tutorial

    Port Number: 5432 by default

  • PostgreSQL ODBC driver (32-bit)

    The 32-bit version of PostgreSQL ODBC driver is required by the PowerBuilder IDE to establish database connection with the PostgreSQL database; therefore the PostgreSQL ODBC driver (32-bit) must be installed on the development PC.

  • PowerBuilder IDE 2021

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

    The PowerBuilder demo database file for PostgreSQL (pbpostgres2021.dmp) will be installed to the %Public%\Documents\Appeon\PowerBuilder 21.0\ directory.


  • PowerBuilder Runtime 2021

  • PowerServer Toolkit 2021

  • SnapDevelop 2021

  • Google Chrome (optional)

Modifying and re-deploying the PowerServer project

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

Step 1: Specify where the Web APIs are actually hosted and run. This tells the client app where and how to call the Web APIs.

On the Web APIs tab of the PowerServer project painter, specify the URL of the docker container where the Web APIs are running. The host name (or IP address) of the docker container should be the same as that of the docker host/Docker Engine. The port number is what will be specified later when the docker container is run, for example, http://172.16.100.20:5009. This indicates that the client app will call the Web APIs running on the docker container at http://172.16.100.20:5009.

Important

  1. Make sure the docker container is run at the same host name (or IP address) and port number. For how to run the image as a container, see the next section Publishing Web APIs to Docker.

  2. If the host name and port number of the docker container 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 2: Configure the database connection.

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

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

  3. Configure the database connection settings (using the PBDemo PostgreSQL database in this tutorial).

    If the following errors occur when testing the connection, try the following solutions:

    • "Exception while connecting"

      Solution: make sure the firewall on the database server has been configured to allow the database port 5432 (detailed instructions).

    • "28000: no pg_hba.conf entry for host "172.16.100.104", user "postgres", database "postgres", SSL off"

      Solution: edit the %PostgreSQL%\12\data\pg_hba.conf file to allow remote connections (detailed instructions).


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

  5. Select the database cache you created just now and map it to the "sqlca" transaction object.


Step 3: Save the PowerServer project settings.

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

Editing the pg_hba.conf file

Open the pg_hba.conf file in a text editor and add the following line.

The pg_hba.conf file is located in %PostgreSQL%\12\data. This enables the database server to allow remote connections.

host    all             all             0.0.0.0/0               md5
Publishing Web APIs to Docker

Step 1: Open the PowerServer Web API solution in SnapDevelop.

Click the Open C# Solution in SnapDevelop button () in the toolbar to launch the Web API solution in SnapDevelop. Or go to the location where the Web API solution is generated; and double click PowerServerApp.sln to launch the solution in SnapDevelop.

At startup, the solution will install/update the dependencies. Wait until the Dependencies folder completes the install/update. (Make sure the machine can connect to the NuGet site: https://www.nuget.org in order to successfully install PowerServer NuGet packages).

Step 2: Add docker support to the ServerAPIs project.

  1. In the Solution Explorer, right click on the ServerAPIs project node, and select Add > Docker Support.

  2. In the Add Dockerfile dialog, select the target OS: Linux or Windows, and click OK. The target OS indicates the platform where Docker Engine and Docker Container are running. In this tutorial, select Linux.

    A file named Dockerfile is automatically created according to the selected OS and added under the ServerAPIs project. This file contains all the commands required for building a docker image appropriate for the selected OS.


Step 3: Build and publish the ServerAPIs project as a docker image.


  1. In the Solution Explorer, right click on the ServerAPIs project node, and select Publish.

  2. In the window that appears, select Docker, and then click Start to configure for publish.

    1. Keep Publish to Personal Repository checked if you are connecting to your own repository (not part of an organization). If the repository is owned by an organization, clear the checkbox, and enter the organization name.

    2. In the Engine field, select the machine where Docker Engine is installed.

      If you select localhost, make sure you have installed Docker Engine on the local machine; if you select a remote machine, make sure you have installed Docker Engine to that machine and configured Docker Engine to allow remote connection. See Setting up a docker host (Docker Engine) for more.

    3. In the Registry field, specify where to store the docker image: Docker Hub or a self-hosted Docker Registry. See Setting up a docker registry for more.

      If you specify a repository in Docker Hub, you will need to enter your Docker username and password.

    4. In the Image Name field, enter a name for the docker image you want to create for the project.

    5. Click Finish to start building the project as an image and publishing the image to the specified Docker Engine and docker registry.


      Check the Docker Output window and make sure the publish is successful.


Step 4: Run the docker image as a docker container.


  1. In SnapDevelop, select View > Docker Explorer to open the Docker Explorer.

  2. In the Docker Explorer, expand the node for the machine where Docker Engine is, and then expand Images and find the image that is created for the project, right click it and select Run as a Container.


  3. In the window that appears, specify the following settings for the container, and click OK.

    • Specify a name for the container.

    • Specify the port number for the Web APIs in the container. Leave the IP address with the default value 0.0.0.0 which will automatically point to the IP address for Docker Engine where the container is running.

      IMPORTANT:

      1. The IP address and port number must match with the Web API URL specified on the Web APIs tab of the PowerServer project painter. And the actual IP address (not 0.0.0.0) should be specified in the Web API URL (view Web API URL).

      2. If the docker host machine connects to Internet via a proxy server, configure the proxy settings as the environment variables (as shown in the blue frame below); or refer to Configure Docker to use a proxy server for detailed instructions.


    The container is started and added under the Containers node. You can stop, restart, or delete the container, or execute commands using the right-click context menu.


    If you double click the container, the container configuration and log will be displayed on the right. The Logs section displays valuable logging information of the Web APIs at runtime.


Specifying Web API URL

Specify where the Web APIs are hosted and run.

On the Web APIs tab of the PowerServer project painter, specify the URL of the docker container where the Web APIs are running, for example, http://172.16.100.20:5009.

IMPORTANT: if the host name and port number of the docker container are changed later, you only need to update the Web API URL and then deploy the project again (using the "Build & Deploy PowerServer Project" option) (it is not necessary to update or re-deploy Web APIs to Docker).