Skip to main content

Managing the Applications Lifecycle

 

OutSystems

Deploying an Application to a Docker Container

Before you start, make sure that:

The following sections contain specific information on using Docker Containers hosting technology and detailed instructions on publishing an application to a Docker container.

Sharing Data with a Docker Container

OutSystems applications running in Docker containers make use of volumes to read information from outside the container, namely configurations and the environment key. This allows the application running inside the container to change its runtime behavior without having to build a new Docker image.

By default, the container has read/write access to these volumes, although applications only require read access. It is possible to set the volume as read-only, which limits the access to the volume by the container and consequently all files that reside in it. This can be done by defining the volumes with :ro tag (read-only).

Configurations Folder

Specifying a mounted volume for the configurations folder allows you to change the settings of OutSystems applications without having to build a new Docker image.

Note: The configurations folder must be mounted even if you don't intend to change application settings at runtime.

You can choose any local folder for this mapping (i.e. the folder that exists on the container host machine), but the configurations folder must be mounted on the c:\configs container folder (i.e. the folder inside the container). When you invoke the docker run command, you specify this mapping between source and target folders using the -v command-line argument, instructing Docker to mount a volume based on this mapping.

Example:
docker run --name <container_name> -d -v <local_configs_folder>:c:\configs:ro -v <local_secrets_folder>:c:\secrets:ro <image_name>

The local folder <local_configs_folder> on the hosting machine is being mapped to the container folder c:\configs in read-only mode.

When deploying a container-bound application to Docker Containers, the OutSystems platform will create an App.config file in the "Output Config Files to" folder specified in the configuration of the deployment zone set for the application. This file must be placed in the local folder that will be mounted (<local_configs_folder> in the example above).

To change OutSystems application settings, place an updated configuration file in the local folder being mapped and the application will automatically fetch the new settings.

Secrets Folder

Some of the platform capabilities use encryption and need an environment key. That key is not distributed with the container code and must exist inside the container in a c:\secrets folder. This key file is named private.key and can be found in the OutSystems platform installation folder (usually C:\Program Files\OutSystems\Platform Server).

Similarly to the the configurations folder, when you start a container image containing an OutSystems application you specify a mount volume for the secrets folder, mapping a local folder to the c:\secrets folder inside the container.

You can choose any local folder for this mapping (i.e. the folder that exists on the container host machine), but the secrets folder must be mounted on the c:\secrets container folder (i.e. the folder inside the container). When you invoke the docker run command, you specify this mapping between source and target folders using the -v command-line argument, instructing Docker to mount a volume based on this mapping.

Example:
docker run --name <container_name> -d -v <local_configs_folder>:c:\configs:ro -v <local_secrets_folder>:c:\secrets:ro <image_name>

The local folder <local_secrets_folder> on the hosting machine is being mapped to the container folder c:\secrets in read-only mode.

SSL Offloading

Make sure you have followed the instructions in End-to-end SSL and SSL Offloading, namely the step for adding a new record to the OSSYS_PARAMETER database.
If these instructions are not followed before publishing the application, you will need to update the configuration of the deployed application.

Publish an Application to a Docker Container

These instructions build upon the general steps outlined in Publish an Application to a Container. Make sure you have read them before proceeding.

1. Compile application and generate bundle

To start the publish process and generate an application bundle, do the following:

  1. In Service Center, navigate to Factory > Applications and click on your application name;

  2. Click the "Publish" button.

Service Center shows the progress of this stage, which includes compiling the application, generating the binaries and providing the application bundle later used to build a container image.

After creating the bundle, Service Center shows two important pieces of information in the last log messages:

Generated bundle filename and full path (ZIP file)

This file is used in the second stage of deploying an application to a container. The filename is defined according to the following template: <ApplicationKey>_<OperationId>.zip

Example:
\\twoflower\luggage\bundles\07897a77-3f58-4e5b-b926-a48605c0b6d0_dab321f9-72e8-44e8-ae5c-2c8212314cf6.zip

Expected result filename and full path for deployment preparation step
The name and path of the result file for the "Preparing Deploy" step that you must provide (either manually or through some automation tool). For now ignore this message, as this will be tackled in step 3.

2. Build container image

In this second stage the operator (either a human person or an automated deployment tool) must perform a set of operations outside the scope of the OutSystems platform.

Note

Make sure that the environment private.key was copied to the local secrets folder (check the "Secrets Folder" section above).

Perform the following steps to create a container image:

  1. Extract the contents of the application bundle ZIP file into a given folder on the machine where Docker is installed.

  2. Copy the App.config configurations file from the deployment zone "Output Configs To" folder to the local configurations folder.
    You can skip this step if you are using the same folder for both purposes (i.e. if the deployment zone's "Output Configs To" folder will be mounted as a Docker container volume in stage 3).

  3. Using PowerShell, navigate to the target folder and build a container image by running the following command:

    docker image build -t <image_name> .

    This command builds an image ready to be launched and registers it in the local Docker registry. The -t tag flag and the argument following it is used to give the image a name.

    Optional: At this point you can register the built image in your central Docker registry, if you are using one.

3. Create result file for the deployment preparation step

During the second step, Service Center is expecting the result file for the "Preparing Deploy" step after building the container image. Thus, you need to create the result file for the "Preparing Deploy" step with the expected name and contents in the configured "Result" folder (the same that appears in the publication messages). The filename must exactly match the expected value and have a .preparedone extension.

Example:
\\twoflower\luggage\results\07897a77-3f58-4e5b-b926-a48605c0b6d0_dab321f9-72e8-44e8-ae5c-2c8212314cf6.preparedone

Follow one of these scenarios according to the result of the deployment preparation operation:

Successful deployment preparation
Create an empty file with the expected name (.preparedone extension) on the configured "Result" folder of the deployment zone.
Failed deployment preparation

Create a JSON file with the correct filename and with a .preparedone extension whose contents follows the template presented next — it contains a user-defined error message:

{"Error":{"Message":"This user-defined error message will appear in the progress log messages in Service Center."}}

Then copy the result file to the configured "Result" folder of the deployment zone.

4. Instantiate container image

In this fourth stage the operator (either a human person or an automated deployment tool) instantiates the previously created container image into a running container.

Perform the following steps to instantiate a container image:

  1. Run the following command in PowerShell:

    docker run --name <container_name> -d -v <host_config_folder>:c:\configs:ro -v <host_secret_folder>:c:\secrets:ro <image_name>

    The two -v parameters will mount volumes for configuration settings and secrets. Replace the <host_config_folder> with the folder on the containers host machine that contains the unified configuration file generated when publishing the application in Service Center and the <host_secret_folder> with the folder on the containers host machine that contains the environment private key (private.key file). Using the :ro suffix will mount both these volumes as read-only.

    If the operation succeeds, this will output the full container ID. The operation will fail if a container already exists with the name <container_name>; in this case, choose a different name for the container, e.g. <container_name>_1.

  2. Check that the container is running by issuing the following command in PowerShell:

    docker ps

    This will output the status and ID of the container. The ID is the first set of 12 hexadecimal characters of the full ID shown in the output.

5. Define network routing rules for container

In this fifth stage the operator checks if the application inside the container is reachable using the deployment zone address.

Usually it’s necessary to define a network routing configuration so that requests coming from outside the container host machine can reach the application modules running inside the container. Note that when the container IP address changes, the routing rules might need to be changed also.

Check if your application modules are reachable using the internal address of the deployment zone configured for the application.
For example, if you have an application with modules "Directory" and "Employees" then they must be reachable at addresses <zone_address>/Directory and <zone_address>/Employees.

You will most probably need to configure several routing rules so that requests coming from outside the container host machine can reach the different application modules running inside the container.

Docker Containers Example: Configure Routing Rules in IIS

Check the Configure Routing Rules in IIS document to learn how you can use IIS to perform the network routing to your application running in a Docker container; the document describes how to define the minimum routing rules needed in this scenario.
Be sure to validate your final routing configuration with your Network and DevOps teams.

6. Create result file for the deployment step

In this stage the operator creates a deployment result file for the "Deploying" step with the expected name and contents in the configured "Result" folder (the same that appears in the publication messages). The filename must exactly match the expected value and have a .deploydone extension.

Example:
\\twoflower\luggage\results\07897a77-3f58-4e5b-b926-a48605c0b6d0_dab321f9-72e8-44e8-ae5c-2c8212314cf6.deploydone

Follow one of these scenarios according to the result of the deployment operation:

Successful deployment
Create an empty file with the expected name (.deploydone extension) on the configured "Result" folder of the deployment zone.
Failed deployment

Create a JSON file with the correct filename and with a .deploydone extension whose contents follows the template presented next — it contains a user-defined error message:

{"Error":{"Message":"This user-defined error message will appear in the progress log messages in Service Center."}}

Then copy the result file to the configured "Result" folder of the deployment zone.

  • Was this article helpful?