Skip to main content

Managing the Applications Lifecycle

 

OutSystems

Deploying an Application to Pivotal Cloud Foundry

Before you start, make sure that:

The following sections contain specific information on using Pivotal Cloud Foundry (PCF) hosting technology and detailed instructions on publishing an application to PCF.

Sharing Data with a PCF-hosted Application

Before deploying your application to PCF you will need to make sure that application configurations file and environment key file are in the correct folders of the application bundle.

Configurations Folder

When deploying a container-bound application to PCF, 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.

You must copy this file to the empty configs folder in the application bundle before proceeding with the deployment operation (i.e. before doing a cf push of the application).

Secrets Folder

Some of the platform capabilities use encryption and need an environment key. The key file is named private.key and can be found in the OutSystems platform installation folder (usually C:\Program Files\OutSystems\Platform Server).

You must copy this file to the secrets folder in the application bundle before proceeding with the deployment operation (i.e. before doing a cf push of the application).

SSL Offloading

Make sure you have followed the instructions in End-to-end SSL and SSL Offloading for adding a new record to the OSSYS_PARAMETER database.
If these instructions are not followed before publishing the application, you will need to republish the application and push it again to PCF.

Publish an Application to PCF

Before publishing your application, ensure that in Pivotal Apps Manager your "org" has the two recommended domain entries, according to the System Requirements for PCF deployments.

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. Push the application to PCF

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.

Perform the following steps to push your application to PCF:

  1. Extract the contents of the application bundle ZIP file into a given folder.

  2. Copy the private.key file from the platform installation folder (usually C:\Program Files\OutSystems\Platform Server) to the secrets folder inside the application bundle.

  3. Copy the App.config file from the "Output Configs To" folder configured for the deployment zone to the configs folder inside the application bundle.

  4. Using PowerShell, navigate to the target folder and run the following command:

    cf push --no-start

    This will push the application to PCF and prepare it to be started. When the command runs successfully, its output will contain the application name on PCF, which is based on the OutSystems application name.

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 pushing the application. 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. Start the container

In this fourth stage the operator (either a human person or an automated deployment tool) starts the previously pushed application.

Perform the following steps to start the container:

  1. Run the following command in PowerShell:

    cf start <app_name>

    Replace the <app_name> with the application name in PCF, as stated in the output of the previous cf push command.

    If the operation succeeds, this will output the status of the application.

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

    cf app <app_name>

    This will output the status of the application.

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.

First, you will need to add route mappings so that the PCF router knows how to handle requests to the applications modules:

  1. In a PowerShell console, execute the following commands to add the routes for each module of your application (repeat for each module name):

    cf map-route <app_name> <public_address> --path <module_name_N>
    cf map-route <app_name> <zone_address> --path <module_name_N>
    

    Replace:

    • <app_name> with the application name in PCF, as stated in the output of the previous cf push command;
    • <public_address> with your public address of your main load balancer and reverse proxy, as described in the PCF requirements;
    • <zone_address> with your PCF zone address (also as described in the PCF requirements);
    • <module_name_N> with the name of the current module.

If the operation succeeds, the command will output the status of the application.

Additionally, you will likely need to configure several routing rules on your main load balancer and reverse proxy so that requests coming from outside your internal network can reach the different OutSystems application modules running inside the Pivotal Cloud Foundry containers.

PCF Example: Define PCF Routes and Configure IIS Routing Rules

Check Define PCF Routes and Configure IIS Routing Rules to learn how you can use IIS to perform the network routing to your application running in a 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.

Check if your application modules are reachable using the internal address of the deployment zone configured for the application and using your public address (if applicable).
For example, if you have an application with modules "Directory" and "Employees" then they must be at least reachable at addresses <zone_address>/Directory and <zone_address>/Employees. If they are meant to be publicly accessible, they will also need to be accessible at addresses <public_address>/Directory and <public_address>/Employees.

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 "Result" folder configured for the application's deployment zone (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?