Skip to main content
Created for OutSystems 11. Not working on your version? Tell us about it!
OutSystems

How to automate Docker container deployment with Jenkins

This document presents a simple container-hosted setup deployment with OutSystems. The information should be used for internal and testing purposes only. We assume that the readers are familiar with the referenced technologies.

You should read the documentation about containers in OutSystems. In particular, the parts about network and deployment zones and publishing to a Docker container.

Prerequisites

To follow the instructions, you need two servers with some software requirements - as outlined below.

Server 1 - OutSystems Machine

  • Windows Server 2016
  • OutSystems Platform Server, including sample apps that can be deployed to containers

Server 2 - Containers Machine

  • Windows Server 2016
  • IIS (ver. 10+), to be used as the as a reverse proxy
  • Docker Enterprise Edition (latest version)
  • Jenkins (ver. 2+ 64 bit)

Additional IIS setup requirements

You need to do some additional setup for IIS. Make sure to:

You can install the extensions on your own, or use this script to automate the installation. Note that this script requires that the PowerShell Execution Police is set to unsigned. For more info check About Execution Policies at Microsoft PowerShell documentation.

Deployment scripts

You will also need the following two sets of scripts:

1. Configure the network

Configure your network so it satisfies these requirements:

  • The OutSystems Machine is accessible from the address defined in the Global Deployment Zone (e.g site.domain.example.com)
  • The Container Machine is accessible from the given address defined in a Deployment Zone (e.g containers.domain.example.com)
  • The Container Machine is accessible to the OutSystems Machine from the port configured for Jenkins (default is 8080)
  • Both machines can reach the OutSystems database

Note: The Global Deployment Zone is the default Deployment Zone. All new applications start in this zone. In practical terms, this means that applications in this zone will be published to the IIS living side-by-side with the OutSystems Platform Front-End.

The automation process itself will:

  • Guarantee that a container is running with the deployed OutSystems application.
  • Create rewrite rules that ensure that the container is reachable from "the outside".

2. Configure the file access

The OutSystems Machine needs to be able to write the application bundle and the configurations to two folders and read the result files from the Containers Machine. The simplest way to achieve this is to create the folders locally in the Container Machine and then create a network share of those folders accessible to the OutSystems machine (with, at least, read and write access for the same user as the one running IIS in that machine). You should have these local folders and their network shares:

  • The Output Files To (or Target Path): created in C:\jenkins\bundles, with the network share at \\containers.domain.example.com\jenkins\bundles
  • The Result (or Result Path): created in C:\jenkins\results, with the network share at \\containers.domain.example.com\jenkins\results
  • The Output Config Files To (or Config Path): created in C:\jenkins\configs, with the network share at \\containers.domain.example.com\jenkins\configs

Here is the overview of the result files:

  • .preparedone for ContainerBuild
  • .deploydone for ContainerRun
  • .undeploydone for ContainerRemove
  • .configsdone for UpdateConfigurations

The emphasized parts correspond to the configuration we will perform later. To get more context about the paths, read the section "Configure the Deployment Zone".

3. Copy the Docker automation scripts

Copy the OutSystems automation scripts to C:\jenkins\ of the Container Machine. The relative paths should remain unchanged. If you place the folders in <your_custom_folder>, make sure you maintain the folders like this: <your_custom_folder>\scripts and <your_custom_folder>\pipelines.

The scripts are used by the pipelines we will set up soon.

4. Set up Jenkins

These are the basic configuration steps to use Jenkins in our testing deployment scenario.

  1. Ensure that you have 64-bit version of Jenkins running. Go to Manage Jenkins > System Information and verify that the value of the java.vm.name is "64-Bit". If not, you must configure Jenkins to use Java x64 before continuing.

  2. Install the PowerShell plugin by going to Manage Jenkins > Plugin Manager > Available tab, searching for PowerShell, checking and selecting Download now and install after restart.

  3. Allow the build triggers to be called anonymously. Go to Manage Jenkins > Configure Global Security and set Jenkins authorization to Anyone can do anything. This has the advantage of allowing build triggers to be called without additional authorization headers, which is acceptable in our current scenario. However, this level of Access Control option should not be used in production.

  4. Allow your containers to access the OutSystems platform private.key. The containers need to have a volume where the private.key is accessible. Copy it to a suitable location. We assume that the private.key was copied to C:\jenkins\secrets in the Containers Machine. The most likely location of private.key is C:\Program Files\OutSystems\Platform Server.

5. Set up the pipelines

We are going to configure four pipelines, one for each of the Deployment Operations (build, run, remove, update). We start with the configuration that is common to all pipelines, and then provide the details for the individual pipelines.

  1. Create a Folder and name it DockerDeployment. Go to Jenkins > New Item. Select the Folder option, enter a name and click OK. It will be used for all pipelines. This keeps things organized.

  2. Create the pipeline. Navigate to Jenkins > DockerDeployment (in the Builds view). Click New Item, select Pipeline, give it a name relevant to the operation and click OK. We chose TheCommonPipeline, but note that TheCommonPipeline is just an example. We suggest using the names that show the action: ContainerBuild, ContainerRun, ContainerRemove, and UpdateConfigurations.

  3. Add the required parameters: Address, ApplicationName, ApplicationKey, OperationId, TargetPath, ResultPath, and ConfigPath. Check the This project is parameterized option, select Add Parameter and then String Parameter. This enables you to create a parameter for the pipeline. Do this for the remaining parameters. Don't forget to click Apply as you go along to save the changes.

  4. In the Build Triggers section, tick the Trigger builds remotely (e.g. from scripts) option and enter an Authentication Token. In our example setup you can use anything you like. This is the value used for the token parameter required to call the URL trigger. This is the last step that's common to all the pipelines. Next we add the Pipeline Scripts specific to each pipeline.

  5. For each of the four pipelines, in the Pipeline section, have Pipeline script selected (optionally, uncheck Use Groovy Sandbox). Copy the pipeline script that corresponds to the respective pipeline and paste it into the Script text area, then modify the paths to those applicable to your specific scenario. Click Save. If Use Groovy Sandbox is checked, you need to manually accept each use of the classes and functions referenced in the code (String, decode64, File, etc.). These can be reviewed by going to Jenkins > Manage Jenkins > In-process Script Approval.

  6. The Pipeline script for the ContainerRun pipeline requires that you customize the parameter MachineFullyQualifiedName to the fully qualified name of the OutSystems machine.

6. Configure the Deployment Zone

Now that we have our automation infrastructure we can create a deployment zone that makes use of it. Let us review the configuration:

  • Name - The name you want to give to your deployment zone (e.g. Container Zone)
  • Internal Address - The fully qualified network name of the publicly accessible endpoint of the deployment zone (e.g. containers.domain.example.com)
  • Output Files To - The network shared folder in the Container Machine where the OutSystems Machine will place the bundles (e.g. \\container.domain.example.com\jenkins\bundles)
  • Result - The network shared folder in the Container Machine where the OutSystems Machine will expect the result files (e.g. \\container.domain.example.com\jenkins\results)
  • Output Config Files To - The network shared folder in the Container Machine where the OutSystems Machine will place the config files for the applications (e.g. \\container.domain.example.com\jenkins\configs)
  • Container Build Trigger URL - The build trigger for the Container Build Jenkins Pipeline we configured (e.g. http://containers.domain.example.com...n=YW1hemluZyE=)
  • Container Run Trigger URL - The build trigger for the Container Run Jenkins Pipeline we configured (e.g. http://containers.domain.example.com...n=YW1hemluZyE=)
  • Update Configurations Trigger URL - The build trigger for the Update Configurations Jenkins Pipeline we configured (e.g. http://containers.domain.example.com...n=YW1hemluZyE=)
  • Container Remove Trigger URL - The build trigger for the Container Remove Jenkins Pipeline we configured (e.g. http://containers.domain.example.com...n=YW1hemluZyE=)

Here is screenshot of a Service Center page, showing the Containers Zone configuration:

7. Test the pipelines

Now that the configuration of Jenkins is finished, try deploying an OutSystems application configured for the deployment zone. You can do it by using Service Center. Check the status of the pipelines in Jenkins > DockerDeployment (following our example). Each build should have a log with more details.